---
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`) and manually override one chat's state (`grix_chat_state_update`). Trigger when the user asks which chats are running/done/waiting, or wants a chat marked done/failed/idle.
---

# Grix Chat State

The Grix account is resolved from the current agent context; you do not pass it.

## 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`

## Rules

1. Never invent a `session_id`. Resolve it with `grix_query` (`session_search`)
   or from a list query first.
2. State overrides are visible to the owner in the App — only set a state the
   user actually asked for, and say which session you changed.
3. On a scope or permission error, report it as-is; do not retry with guessed
   parameters.