---
name: grix-widget-visitor-ban
description: Ban a widget visitor session with the typed `grix_widget_visitor_ban` tool — blocks the visitor's chat session and automatically adds the session's most recent init IP to the owner's global IP ban list (7-day expiry by default). Trigger when the owner asks to ban, block, or kick an abusive/spamming widget visitor.
trigger: When the owner wants to ban, block, or kick an abusive or spamming widget visitor session
---

# Grix Widget Visitor Ban

Banning a widget visitor is a server-side enforced moderation action:

- **Permission is granted per agent by the owner.** The platform checks that the
  calling agent has the "ban widget visitor" permission; the agent is only the
  caller. If the owner has not granted it, the call is rejected — nothing the
  agent says or retries can bypass that.
- **The ban is twofold.** The visitor's session is banned, and the session's
  most recent init IP is automatically added to the owner's global IP ban list
  (expires in 7 days by default).

## Tool contract

Call `grix_widget_visitor_ban` with:

- `session_id` (required) — the widget visitor session ID to ban. It must be a
  widget visitor session owned by your owner, not a regular user/agent session.

On success the result carries the banned `session_id`, the resolved
`visitor_key`, and the new session `status`.

## Rules

1. Banning is an irreversible moderation action (the IP ban outlives the
   session) — confirm with the owner before calling, and pass exactly the
   `session_id` they mean.
2. `session_id` must be a widget visitor session; do not pass regular chat
   session IDs.
3. If the call fails with a permission error, the owner has not granted this
   agent the "ban widget visitor" permission — tell the owner to enable it in
   the agent's permission settings in the App. Do not retry; it will keep
   failing.
4. If the call fails with a not-found error, the session is invalid or does not
   belong to your owner — report that instead of guessing another ID.
5. On any failure, report the exact reason to the owner instead of silently
   retrying.