---
name: grix-query
description: Use the typed `grix_query` tool for Grix contact lookup, keyword search, session search, favorited-session search, and session message history lookup. Trigger when users ask to find contacts, search conversations, list visible or favorited sessions, or inspect recent messages in a known session.
trigger: When the user wants to find contacts, search sessions, list visible or favorited sessions, or read message history of a known session
---

# Grix Query

Use the `grix_query` tool for read-only Grix lookup. This skill only queries
existing contacts, sessions, and raw session messages — it never sends or
changes anything.

## Tool contract

Always call the `grix_query` tool with one `action`:

- `contact_search` — find contacts. Use exactly one mode: exact lookup with
  `id`, keyword search with `keyword`, or list-all with neither.
- `session_search` — find sessions. Same three modes as `contact_search`. Each result includes
  `session_type` (1 = private chat, 2 = group chat). To filter by type pass `sessionType`: `1`
  for private chats only, `2` for group chats only. **Omitting `sessionType` returns all sessions
  regardless of type.** A fourth mode: `peerId` (a user ID) returns the private chat between the
  current user and that account exactly, via the pair key rather than the title — use it whenever
  you know the target user's ID (e.g. "contact the agent owner, user 123"). It takes precedence
  over `id`/`keyword`; error `4004` means no private chat exists with that user yet.
- `search_favorite_sessions` — list the owner's favorited sessions; optional
  `keyword` filter.
- `message_history` — read recent clean messages in a session. Requires
  `sessionId`; defaults to the newest one message and pages backwards with
  `beforeId`. Agent history contains plain text and approval-family cards, not
  tool/status/binding process cards.
- `message_search` — keyword search inside a session. Requires `sessionId` and
  `keyword`; page backwards with `beforeId`.

Other parameters: `limit` (1–100), `offset`.

## Rules

1. Parse the request into exactly one action before calling.
2. If both `id` and `keyword` are given, the backend prioritizes `id`; do not
   send both unless you explicitly want exact-match behavior.
3. For message history or in-session search when no `sessionId` is known, first
   locate the session via `session_search`, or ask the user for a precise target.
4. When a result is paginated and `has_more` is true, keep paging only when the
   user asked for everything, the target is still unresolved, or one page is
   clearly insufficient.
5. On scope/auth/parameter errors, report the exact failure and the fix; do not
   silently retry with guessed parameters.