Governance challenge actions — PROMPT and ALLOW_WITH_OVERRIDE

The Arbitex policy engine supports two governance challenge actions that let admins require user acknowledgement before sensitive requests are processed: PROMPT and ALLOW_WITH_OVERRIDE. Both actions intercept a request mid-flight and present the user with a governance challenge in the chat interface. The difference is what happens next: PROMPT requires the user to actively confirm before continuing, while ALLOW_WITH_OVERRIDE lets the user proceed immediately after acknowledging the risk.

Source: backend/app/services/policy_engine.py

---

Action overview

Action	Effect	User can proceed?	Audit record
PROMPT	Presents a challenge dialog; user must confirm before the request is processed	Yes, after confirmation	Yes — override logged with rule ID and timestamp
ALLOW_WITH_OVERRIDE	Presents an acknowledgement message; user proceeds immediately	Yes, unconditionally after acknowledgement	Yes — override logged with rule ID and timestamp
BLOCK	Hard deny — request is rejected with a configurable error message	No	No override

Both PROMPT and ALLOW_WITH_OVERRIDE are terminal actions — when a rule fires with either action, no further rules in the chain are evaluated (in first_applicable mode).

---

PROMPT action

When it triggers

A rule with action PROMPT fires when:

1. All rule conditions match the request context (provider, model, user groups, content regex, entity types, risk score, intent complexity).
2. The request channel is interactive — i.e., the request originates from a browser or SSE session. PROMPT does not fire on API (programmatic) callers; if the channel condition is not set on the rule, the action fires on both channels, but the frontend challenge UI is only available to interactive callers.

Channel enforcement: The channel condition in a rule’s conditions block restricts which channel types the rule applies to. To ensure PROMPT only fires for interactive users and silently passes for API callers, configure the rule with:

{
  "conditions": {
    "channel": ["interactive"]
  },
  "action": {
    "type": "PROMPT",
    "prompt_message": "This request touches sensitive financial data. Please confirm you intend to proceed."
  }
}

If channel is omitted from conditions, the rule fires for all callers. API callers receiving a PROMPT decision receive a structured error response indicating governance intervention.

User experience — governance challenge flow

When a PROMPT decision is returned for an interactive session:

1. The chat interface renders a governance challenge dialog in the message stream, replacing the pending response indicator.
2. The dialog displays the admin-configured prompt_message (or a default message if none is configured).
3. The user sees two options: Confirm and Cancel.
4. Confirm: The request is re-submitted with an override token. The platform processes the request normally and the response streams back.
5. Cancel: The request is abandoned. An audit record is written with action prompt_cancelled.

The challenge dialog is rendered as an SSE event of type governance_challenge and displays inline in the conversation thread.

Configuring the PROMPT action

In the policy rules admin UI (Admin > Policy Engine > Packs > Rules), set the rule action to PROMPT and optionally fill in Challenge message:

Field	Required	Description
type	Yes	"PROMPT"
prompt_message	No	Custom text displayed in the governance challenge dialog. If omitted, a default platform message is shown.

API configuration:

{
  "name": "High-risk model PROMPT",
  "applies_to": "input",
  "conditions": {
    "models": ["gpt-4o", "claude-opus-4"],
    "user_groups": ["contractors"],
    "channel": ["interactive"]
  },
  "action": {
    "type": "PROMPT",
    "prompt_message": "This request uses a high-capability model restricted for contractor accounts. Confirm you have approval to proceed."
  }
}

---

ALLOW_WITH_OVERRIDE action

When it triggers

ALLOW_WITH_OVERRIDE fires when rule conditions match, regardless of channel. Unlike PROMPT, it does not block the request waiting for user input — it records the override and allows the request to proceed.

Use ALLOW_WITH_OVERRIDE when:

• You need an audit trail that a user knowingly sent a request matching a sensitive policy rule.
• The risk is low enough that a hard block or interactive confirmation is not warranted.
• You want the user to see a notice that their request matched a policy (informational governance).

User experience

When ALLOW_WITH_OVERRIDE fires in an interactive session:

1. The chat interface briefly displays the admin-configured override_message as a notice banner above or below the response.
2. The request is processed immediately — no confirmation required.
3. The override is logged (see Override audit trail below).

For API callers, the response includes an X-Policy-Override: true header and the policy decision is included in the response metadata. The request proceeds normally.

Configuring the ALLOW_WITH_OVERRIDE action

{
  "name": "PII detected — override notice",
  "applies_to": "input",
  "conditions": {
    "entity_types": ["EMAIL_ADDRESS", "PHONE_NUMBER"],
    "entity_confidence_min": 0.8
  },
  "action": {
    "type": "ALLOW_WITH_OVERRIDE",
    "override_message": "Your message contains personal information (email/phone). This interaction is logged for compliance."
  }
}

Field	Required	Description
type	Yes	"ALLOW_WITH_OVERRIDE"
override_message	No	Notice text displayed to the user. If omitted, no visible notice is shown, but the override is still logged.

---

Channel condition

The channel condition restricts rule evaluation to specific request origins:

Channel value	Description
"interactive"	Browser/SSE callers — the chat web UI or any client that uses Server-Sent Events
"api"	Programmatic API callers — M2M tokens, scripts, integrations

Rules without a channel condition apply to all callers.

Recommended pattern for PROMPT rules: Always add "channel": ["interactive"] to PROMPT rules. Without this restriction, API callers receive a PROMPT decision and must implement client-side handling for the governance challenge flow. Most API integrations are not built for interactive confirmation dialogs.

{
  "conditions": {
    "user_groups": ["external-users"],
    "channel": ["interactive"]
  },
  "action": {
    "type": "PROMPT",
    "prompt_message": "External user access to this model requires confirmation."
  }
}

---

Override audit trail

Every PROMPT confirmation and every ALLOW_WITH_OVERRIDE request generates an audit log entry. The override record includes:

Field	Description
action	"prompt_override" or "allow_with_override"
user_id	UUID of the user who triggered the override
rule_id	UUID of the policy rule that fired
pack_id	UUID of the policy pack containing the rule
rule_name	Human-readable rule name
match_reason	Why the rule matched (conditions that were satisfied)
channel	"interactive" or "api"
timestamp	ISO-8601 UTC timestamp of the override

Override records are included in the standard audit log export and compliance reports. Filter by action = "prompt_override" or action = "allow_with_override" to see governance challenge activity.

Viewing overrides: In the Admin portal, navigate to Audit Log and filter by action type. The override.count OTel metric (arbitex.override.count labeled by rule_id) tracks override frequency for alerting purposes.

---

Policy evaluation severity

In the policy engine’s deny_overrides combining algorithm, PROMPT has severity 1 (above ALLOW at 0, below ROUTE_TO at 2 and BLOCK at 5). ALLOW_WITH_OVERRIDE is treated as a terminal action in first_applicable mode.

Severity table (higher = more restrictive):

Action	Severity
ALLOW	0
PROMPT	1
ROUTE_TO	2
REDACT	3
CANCEL	4
BLOCK	5

In deny_overrides mode, a BLOCK or CANCEL in any rule always wins over a PROMPT. In first_applicable mode (the default), the first matching terminal rule wins regardless of severity.

---

Common configurations

Require confirmation for high-risk models (interactive only)

{
  "name": "High-capability model confirmation",
  "applies_to": "input",
  "conditions": {
    "models": ["gpt-4o", "claude-opus-4-6", "o1"],
    "channel": ["interactive"]
  },
  "action": {
    "type": "PROMPT",
    "prompt_message": "You are using a high-capability model. Requests are logged and reviewed. Confirm to proceed."
  }
}

Compliance notice for PII-containing requests

{
  "name": "PII compliance notice",
  "applies_to": "input",
  "conditions": {
    "entity_types": ["SSN", "CREDIT_CARD", "PASSPORT"],
    "entity_confidence_min": 0.85
  },
  "action": {
    "type": "ALLOW_WITH_OVERRIDE",
    "override_message": "Sensitive personal data detected. This session is being recorded for compliance purposes."
  }
}

Risk-score gated confirmation

{
  "name": "Elevated-risk user confirmation",
  "applies_to": "input",
  "conditions": {
    "user_risk_score_min": 0.7,
    "channel": ["interactive"]
  },
  "action": {
    "type": "PROMPT",
    "prompt_message": "Your account has elevated security flags. This request requires explicit confirmation."
  }
}

---

See also

• Policy engine overview — chain structure, combining algorithms, all action types
• Policy simulator — test rules against sample prompts before deploying
• Audit log management — filtering, exporting, and retaining audit records
• DLP pipeline configuration — entity detection that feeds the entity_types condition