---
name: grix-chat-state
description: Observe and manage chat task state — query the task state of all the owner's chats (`grix_chat_state_query`), manually override one chat's state (`grix_chat_state_update`), and check the current MCP connection status (`grix_status`). Trigger when the user asks which chats are running/done/waiting, wants a chat marked done/failed/idle, or wants to verify the Grix connection is healthy.
trigger: When the user asks which chats are running / done / waiting for approval, wants a chat's task state changed, or wants to confirm the Grix connection is healthy
---

# Grix Chat State & Status

## Query chat task states — `grix_chat_state_query`

Read-only; safe to call any time to orient yourself. Returns one entry per
session (direct and group) 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

Parameters (all optional):

- `session_id` — query a single session; omit to list all sessions
- `page` (default 1), `page_size` (default 10, max 100)
- `state` — filter by one state

Each entry carries `task_title`. When `session_id` targets exactly one
**completed** session, the entry also contains one `final_result` object:
`found`, and when found `msg_id`, `content`, `created_at`. Use that
`final_result` directly — do not query message history merely to recover a
dispatched task's result. List queries and non-completed sessions never
include message content.

## Override a chat's state — `grix_chat_state_update`

Sets the task state of one session, e.g. to mark a chat done, failed, or idle
outside the normal task lifecycle. It only updates an **existing** state
record and errors if the session has none.

- `session_id` (required)
- `state` (required) — one of `running`, `waiting_approval`,
  `waiting_question`, `completed`, `failed`, `idle`
- `reason` (optional) — written to `stop_reason`

## Connection status — `grix_status`

No parameters. Returns the Grix connection status of the current MCP session;
use it to confirm you are connected before relying on other `grix_*` tools.