feat(guardrails): per-team opt-out for specific global guardrails

[ryan-crabbe-berri]

Summary

Adds a per-guardrail opt-out for global (default_on) guardrails on a team, alongside the existing all-or-nothing kill switch. Backed by a new disabled_global_guardrails: List[str] field on team metadata that the request-time gate checks before running each global guardrail.

• Backend: CustomGuardrail.should_run_guardrail now consults disabled_global_guardrails and skips the guardrail when its name is present and default_on=True. litellm_pre_call_utils propagates the field from team metadata onto the request.
• UI: Team edit page replaces the flat guardrails Select with a grouped (Global / Other) multi-select, with green chips for globals and blue for opt-ins. On save the UI partitions the user's selection into metadata.guardrails (extras) and metadata.disabled_global_guardrails (globals NOT chosen).
• Refactor: useGuardrails now exposes the full guardrail objects plus derived globalGuardrailNames / optionalGuardrailNames sets via React Query's select. The old useGuardrailsList.ts (which only returned names) is removed and AddModelForm updated to consume the new shape.
• Includes fix(guardrails): use plural key in get_disable_global_guardrail #25488

CircleCI: https://app.circleci.com/pipelines/github/BerriAI/litellm/73458/workflows/3356a97c-841f-4c61-83ef-67527878801f

Screenshots

Test plan

• useGuardrails hook tests pass (10 tests)
• TeamInfo tests pass (25 tests)
• Manual: open a team with a global guardrail enabled, edit, deselect that one global, save → verify request-time skips that guardrail for this team but still runs it for others
• Manual: open a team with no opt-outs, edit, save without changes → verify disabled_global_guardrails saves as [] and globals still apply
• Manual: trigger the loading state by throttling network → verify edit form shows "Loading..." until the guardrails query resolves

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Apr 13, 2026 7:22pm

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing litellm_feat-per-guardrail-opt-out-for-global-guardrails (2d14e4a) with main (d319cd8)}

[greptile-apps]

Greptile Summary

This PR adds per-guardrail opt-out for global (default_on=True) guardrails at the team level, alongside the existing all-or-nothing kill switch. The backend plumbing (opted_out_global_guardrails propagation through litellm_pre_call_utils and the guard in should_run_guardrail) is clean and well-tested. The UI introduces a grouped Select and a new GuardrailSettingsView component that correctly partition and display global vs. team-specific guardrails.

Several edge-case concerns were surfaced in earlier review cycles (kill-switch toggle re-enabling opted-out globals, error state not guarded, duplicate entries for legacy teams); addressing those before merge would improve reliability of the opt-out feature.

Confidence Score: 4/5

Backend logic is safe; UI has open edge-case concerns from prior review cycles that could silently corrupt a team's opt-out configuration.

The backend (custom_guardrail.py, litellm_pre_call_utils.py) is correct and well-covered by unit tests. New findings are P2 only. However, earlier rounds flagged several P1 UI issues (error-state data loss, kill-switch toggle re-enabling previously opted-out globals) that appear unaddressed in the current code, keeping the score at 4 rather than 5.

ui/litellm-dashboard/src/components/team/TeamInfo.tsx — kill-switch toggle, error state, and legacy-team duplicate-entry edge cases.

Important Files Changed

Filename	Overview
ui/litellm-dashboard/src/components/team/TeamInfo.tsx	Major UI overhaul: grouped select, per-guardrail opt-out save logic, kill-switch interaction, and GuardrailSettingsView integration; several edge cases flagged in prior review remain (error state, kill-switch toggle, duplicates).
litellm/integrations/custom_guardrail.py	Adds get_opted_out_global_guardrails_from_metadata and a per-guardrail skip in should_run_guardrail; renames disable_global_guardrail key to plural form (breaking change noted in prior review).
litellm/proxy/litellm_pre_call_utils.py	Correctly propagates opted_out_global_guardrails from team_metadata to the request metadata with an isinstance list guard; mirrors the existing disable_global_guardrails pattern.
ui/litellm-dashboard/src/app/(dashboard)/hooks/guardrails/useGuardrails.ts	Refactored to expose full guardrail objects and derived globalGuardrailNames/optionalGuardrailNames sets via React Query select; breaking change to hook return type handled correctly in consumers.
ui/litellm-dashboard/src/components/GuardrailSettingsView.tsx	New presentational component for displaying global vs team-specific guardrail state; handles kill-switch, opt-outs, and empty states correctly.
tests/test_litellm/integrations/test_custom_guardrail.py	Adds comprehensive tests for opted_out_global_guardrails covering root/litellm_metadata/metadata paths, malformed inputs, non-global guardrail immunity; existing tests updated from singular to plural key.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Incoming Request] --> B[litellm_pre_call_utils\nPropagate team metadata]
    B --> C{team has\nopted_out_global_guardrails?}
    C -- Yes --> D[Write to litellm_metadata.\nopted_out_global_guardrails]
    C -- No --> E[Write to litellm_metadata.\ndisable_global_guardrails]
    D --> E
    E --> F[should_run_guardrail]
    F --> G{default_on = True?}
    G -- No --> H[Check requested_guardrails list]
    G -- Yes --> I{guardrail_name in\nopted_out_global_guardrails?}
    I -- Yes --> J[Return False\nSkip guardrail]
    I -- No --> K{disable_global_guardrail\n= True?}
    K -- Yes --> J
    K -- No --> L{Event hook matches?}
    L -- Yes --> M[Run Guardrail]
    L -- No --> N[Return False]
    H --> O{guardrail in\nrequested list?}
    O -- Yes --> L
    O -- No --> N

Loading

_{Reviews (7): Last reviewed commit: "test(ui/team): fix guardrails overview t..." | Re-trigger Greptile}

[greptile-apps]

Breaking rename of disable_global_guardrail to disable_global_guardrails

get_disable_global_guardrail now exclusively checks for the plural key disable_global_guardrails, dropping the old singular form. Any caller who was passing disable_global_guardrail: true (singular) directly in request data or litellm_metadata/metadata will silently find the kill switch no longer working after this deploy. The old test cases were explicitly exercising this direct-request path with the singular key, confirming it was the supported API contract.

The team-metadata path was already writing the plural form (via litellm_pre_call_utils.py), so there's a legitimate fix here — but it should be additive rather than a hard rename:

def get_disable_global_guardrail(self, data: dict) -> Optional[bool]:
    """Returns True if the global guardrail should be disabled"""
    # Check plural (new) then singular (backwards compat)
    if "disable_global_guardrails" in data:
        return data["disable_global_guardrails"]
    if "disable_global_guardrail" in data:  # legacy key
        return data["disable_global_guardrail"]
    metadata = data.get("litellm_metadata") or data.get("metadata", {})
    if "disable_global_guardrails" in metadata:
        return metadata["disable_global_guardrails"]
    if "disable_global_guardrail" in metadata:  # legacy key
        return metadata["disable_global_guardrail"]
    return False

Rule Used: What: avoid backwards-incompatible changes without... (source)

[greptile-apps]

Error state not guarded — silent opt-out data loss

The loading check gates on isGuardrailsLoading but not on the error state. When the guardrails query fails (network error, service down, etc.), isGuardrailsLoading becomes false while guardrailsData stays undefined, so globalGuardrailNames falls back to new Set<string>(). If the user opens the edit form in that state and saves — even without making changes — optedOutGlobalGuardrails is computed as [] and overwrites whatever was previously stored, silently re-enabling any globals the team had opted out of.

You'd also need to destructure isError: isGuardrailsError from the useGuardrails() call on line 183.

[greptile-apps]

Kill-switch toggle ON → OFF silently re-enables previously opted-out globals

When a team has, say, guardrail A opted out and B active, the form initializes with guardrails = [B, ...]. Toggling the kill switch ON removes B; toggling it back OFF calls [...Array.from(globalGuardrailNames), ...nonGlobals], which unconditionally adds all global guardrails — including A — back to the selection. Saving at that point computes optedOutGlobalGuardrails = [] and silently re-enables A for this team.

The fix is to snapshot which globals were selected before the kill switch was enabled and restore only those on disable:

onValuesChange={(changedValues) => {
  if ("disable_global_guardrails" in changedValues) {
    const checked = changedValues.disable_global_guardrails === true;
    const current = (form.getFieldValue("guardrails") || []) as string[];
    const nonGlobals = current.filter((n) => !globalGuardrailNames.has(n));
    const prevGlobals = current.filter((n) => globalGuardrailNames.has(n));
    form.setFieldValue(
      "guardrails",
      checked ? nonGlobals : [...prevGlobals, ...nonGlobals],
    );
  }
}}

Using prevGlobals (globals that were selected before the toggle) instead of Array.from(globalGuardrailNames) preserves the team's existing per-guardrail opt-out state across a kill-switch round-trip.