Contesting a block

Every block EgisAI produces is the right block on the rules the operator authored — but operators do sometimes find a block that was overly broad, or a sanitize that should have been an allow. This page documents the operator workflows for contesting a decision, marking it for review, and turning a wrong block into a policy change without losing the original evidence. The contract here is deliberately operator-side, not end-user-side. EgisAI never sees the end user directly — your application does — so we do not ship an end-user appeal portal. Instead we surface enough signal on the dashboard for your operator to triage, review, and act, with the review trail captured on the audit row.

​

The four operator actions

When an operator opens a request-detail drawer and concludes the verdict was wrong, the workflow is one of four actions: Each action is captured with the actor, the captured display label, the IP, the user-agent, and a metadata snapshot. The audit trail is enough for a SOC 2 reviewer to confirm the chain of custody after the fact.

​

The per-request review state

The dashboard request-detail drawer carries a Mark for review control. Marking a request flips its review_state to a defined value and writes an operator-action audit row. The supported states are: Transitions between states are themselves audit-logged (request.review_state_changed) with the actor, the prior state, and the new state, so the chain “who decided this verdict was wrong, when?” is queryable from the operator-action audit log. The review state is exported as a column in request_logs.csv so a fairness or audit review can filter on “blocks that were reviewed and confirmed incorrect.”

​

A worked example

A customer-service agent is blocked from telling a customer their order status because a deny regex matched on the order id format. The operator’s path:

1. Open the request in the dashboard. The decision drawer shows the matched policy was pii-orderid-blocked, enforcement_status is enforced, and the post-redaction preview reveals the block was triggered by an order-id pattern that overlaps a credit-card mask.
2. Mark for review with state reviewed_incorrect. The operator adds a one-line note: “Order-id regex over-broad; collides with the CC mask.”
3. Edit the policy. They open the pii-orderid-blocked policy, narrow the regex, and save. A policy.update row lands in the audit log with the captured metadata (priority, phase, target agents).
4. The SDK picks up the new policy on its next refresh. Subsequent calls with the same order-id pattern allow correctly.

A month later, an auditor reviewing the operator-action audit log sees:

• the review-state transition (operator, time, prior + new state, note),
• the policy.update row (operator, time, policy id, metadata diff),
• the request_logs rows for that policy across the window, with verdict distribution before and after the policy edit.

That is the complete contest-to-resolution evidence pack.

​

When to escalate, not edit

Some blocks are correct but uncomfortable. A semantic_guard block on a borderline harassment intent, an output regex block on an unusual financial format, a pii_scan block on a customer-provided identifier that turned out to be intentional — these are cases where the right action is to escalate to a reviewer or to the compliance team, not edit the policy. The supported pattern is:

1. Mark the request for review with state escalated.
2. Send the request id (and optionally the post-redaction preview) to the human reviewer through your team’s normal channel — Slack, email, ticketing.
3. Have the reviewer mark the request reviewed_correct or reviewed_incorrect when they conclude.

The audit row captures both the escalation transition and the resolution transition, so the regulator-style question “show me every semantic-guard block this quarter that a human reviewer touched” is a one-line query on request_logs.csv.

​

What we deliberately don’t ship

To be explicit about scope:

• No end-user-facing appeal portal. EgisAI never sees the end user directly; the customer’s application does. Surfacing a “contest this decision” link to the end user is a customer-side feature — the SDK block path returns enough information (the matched policy id, the reason code, the post-redaction preview) for the customer’s application to render a help page or a support form.
• No automatic un-blocking. Marking a request reviewed_incorrect records the operator’s judgement; it does not retroactively change the verdict. The historical row stays as the model saw it.
• No “trust me” overrides. There is no mechanism for an operator to re-run a blocked call with the block disabled “just for this request”. If a class of calls is being incorrectly blocked, the path forward is to edit the policy and let the new ruleset apply going forward.

These constraints are intentional: an audit-grade system records what happened and lets the operator fix the rules forward, not re-run the past.

​

Choosing between raise and stub

Your code can see a block in two ways, picked by the on_block configuration:

• raise (default) raises PermissionError with the reason embedded. Your existing exception handlers can catch it and route to your application’s error path.
• stub returns a framework-shaped refusal object — same shape as the provider would have produced, with content describing that the call was refused by policy.

Long-running agent loops that should not crash on a single bad turn typically use stub; user-facing call paths usually use raise. See Blocking behavior for full examples.

​

Roadmap

The capabilities below are designed and on the near-term roadmap, in this order:

1. First-class review-state column. A request_logs.review_state column plus a dashboard control to set it. The audit-evidence export surfaces the state as a column for fairness joins.
2. Reviewer-only role. A workspace role that can transition review state but cannot author policies. Useful for compliance teams that should review without touching the runtime rules.
3. SLA timers on escalated reviews. Optional per-org timer that surfaces overdue escalations as a dashboard counter.

When each of these lands we’ll update this page with the operator workflow.

​

What’s next