---
name: grix-chat-state
description: Observe chat state — query the task state of all the owner's chats (`grix_chat_state_query`), and check the current MCP connection status (`grix_status`). Trigger when the user asks which chats are running/done/waiting, or to verify the Grix connection is healthy.
trigger: 当用户问哪些聊天任务在跑/已完成/在等待审批,或要确认 Grix 连接是否正常时
---

# Grix Chat State & Status

Read-only observation of chat task state and connection state.

## Chat task states — `grix_chat_state_query`

Query the task state across all the owner's chats (direct and group sessions).
Supports pagination and optional state filtering.

Parameters:
- `session_id` — query a single session; omit to return all sessions
- `page` — page number, default 1
- `page_size` — items per page, default 10, max 100
- `state` — filter by state; omit to return all

Returns one entry per session with a single mutually-exclusive state:

- `running` — working
- `waiting_approval` — blocked on the owner to approve/deny
- `waiting_question` — asked the owner a question, awaiting reply
- `completed` / `failed` — finished
- `idle` — no task / stopped

Also returns `task_title` for easy identification of each chat.

Use it to see at a glance which chats are done, still running, or waiting on the
owner.

## Connection status — `grix_status`

Query the Grix connection status of the current MCP session. Takes no
parameters. Use it to confirm the agent is connected before relying on other
grix tools.

## Manually update a chat state — `grix_chat_state_update`

Override the task state of a specific chat session. Useful when you need to
mark a chat as done, failed, or idle outside of a normal task lifecycle.

Parameters:
- `session_id` — **(required)** the session to update
- `state` — **(required)** one of: `running`, `waiting_approval`, `waiting_question`, `completed`, `failed`, `idle`
- `reason` — **(optional)** reason for the change, written to `stop_reason`

## Rules

1. `grix_chat_state_query` is read-only — safe to call any time to orient yourself.
2. `grix_chat_state_update` only updates existing records; it will error if the session has no prior state entry.
3. `grix_chat_state_query` reports per-session state, not per-message; pair it with
   `grix_query` (`message_history`) when you need the actual content.