---
name: grix-group
description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, leave, update, or dissolve groups, or when these operations fail with scope or permission errors.
---

# Grix Group

Use `grix_group` for group lifecycle and membership management. The Grix
account is resolved from the current agent context; you do not pass it.

## Tool contract

Call `grix_group` with one `action`; use the exact typed field names below.

| `action` | Required | Optional |
|---|---|---|
| `create` | `name` | `memberIds` (numeric strings) + `memberTypes` (1=user, 2=agent), aligned by index |
| `detail` | `sessionId` | — |
| `leave` | `sessionId` | — (never send member fields) |
| `dissolve` | `sessionId` | — |
| `add_members` / `remove_members` | `sessionId`, `memberIds` | `memberTypes`, aligned by index |
| `update_member_role` | `sessionId`, `memberId`, `role` (1=admin, 2=member) | — (`memberType` is always 1) |
| `update_all_members_muted` | `sessionId`, `allMembersMuted` | — |
| `update_member_speaking` | `sessionId`, `memberId`, at least one of `isSpeakMuted` / `canSpeakWhenAllMuted` | `memberType` (1 or 2) |

## Rules

1. Validate required fields before calling; reject non-numeric `memberIds`
   and empty `sessionId` yourself. Resolve an unknown or ambiguous group with
   `grix_query` (`session_search`) and confirm with the user first.
2. One call per business action. `create` and `dissolve` are not idempotent —
   never auto-retry them; ask for explicit confirmation before repeating.
3. Never guess a role or mute state from vague wording; confirm whether the
   user wants it enabled or disabled.
4. `leave` removes only the current agent from the group. Execute it only
   for the owner or an already-established authorized operator; if identity
   is unclear, confirm first. Leave silently — no farewell message — and
   report the result only to the requester. To remove someone else use
   `remove_members`. `leave` needs no scope, so never answer a `leave`
   failure with scope-grant guidance.
5. On errors, report the exact failure and fix; do not retry blindly:
   - `403/20011` — missing scope (usually not an admin of that group); ask the
     owner to grant it in the agent permission page.
   - `401/10001` — invalid key/auth; check agent config or rotate the key.
   - `403/10002` — agent not active or invalid provider type.
   - `400/10003` — invalid or missing parameters.

## Response style

State the result first with key identifiers (`session_id`, member count,
mute state); on failure give the exact remediation and never hide scope or
auth errors behind generic wording.

## Reference

[references/api-contract.md](references/api-contract.md) — exact tool
mapping, payload examples, and scope matrix.