---
url: https://clusto.app/docs/agent-attention.md
description: >-
  Understand the question-mark waiting-for-input marker, copy-prompt
  notifications, and the tool-agnostic contract any AI CLI can use to drive
  them.
---

# Agent Waiting-for-Input Marker

When an AI agent running inside a Clusto terminal session blocks on you - a
permission prompt, a question, or any input request it can't proceed without -
Clusto marks that session and can notify you. This lets you walk away from a long
agent run and come back exactly when it actually needs an answer.

There are two parts:

* A **waiting marker** in the sidebar: an amber question disc on the session
  row, a `?` before its name, and waiting counts on the project folder and the
  **Terminals** header, so you can spot a waiting session at a glance.
* An optional **notification with a Copy button** that copies the question /
  prompt text, so you can paste it elsewhere.

## The waiting marker

The marker appears whenever the agent in that session is genuinely **asking
for an answer** - not merely when it has stopped or finished a turn. A
finished-but-unanswered turn does not earn it.

The marker is driven by signals the agent reports to the daemon, so every
connected device shows the same state. It clears as soon as the agent reports
it is no longer waiting. The counts span every online node; **Go to next
waiting session** in the `F1` command palette jumps to each waiting session in
turn. See [Sidebar markers](/terminal-workspace#sidebar-markers) for the other
row markers.

## Set up automatically

Claude Code, Codex, opencode, Gemini CLI and GitHub Copilot CLI need no manual
setup. Every node wires the marker for them as part of its periodic [AI setup](/knowledge#what-happens-on-each-node)
reconcile, which runs when the daemon starts, after knowledge changes and every
5 minutes. The AI setup page lists one check per tool: **Claude Code waiting
status**, **Codex waiting status**, **opencode waiting status**, **opencode
MCP server**, **Gemini CLI waiting status** and **GitHub Copilot CLI waiting
status**. If one is not green, run **Fix now** there, or use
[Node Doctor](#node-doctor) to fix every node at once.

### Claude Code

Clusto adds its own hook entries to the agent user's `~/.claude/settings.json`
(or `$CLAUDE_CONFIG_DIR/settings.json`):

| Hook | Matcher | Runs |
|---|---|---|
| `Notification` | `permission_prompt\|elicitation_dialog` | `clusto internal notify-state --waiting` |
| `PreToolUse` | `AskUserQuestion` | `clusto internal notify-state --waiting --reason question` |
| `PostToolUse` | `AskUserQuestion` | `clusto internal notify-state --idle` |
| `Stop` | - | `clusto internal notify-state --idle` |
| `UserPromptSubmit` | - | `clusto internal notify-state --idle` |
| `StopFailure` | `server_error\|overloaded` | `clusto internal notify-state --failed` |

* Clusto recognises its entries by their `internal notify-state` command. Your
  own hooks are never changed or removed.
* The command is the absolute path of the `clusto` CLI installed next to
  `clustod`, so it works even when `clusto` is not on the agent's `PATH`.
  Outside a Clusto session the command exits silently.
* The `idle_prompt` notification is deliberately not wired, so a
  finished-but-unanswered turn does not produce a false `?`.
* For `AskUserQuestion`, the text behind the **Copy** button is the question
  from the hook payload.

### Codex

Nothing is written. Codex 0.166 and later report approvals and questions with
[OSC 7501](/terminal-notifications) on their own. Older Codex releases show an
`Action Required` terminal title while they wait, which Clusto reads instead.
Either way the marker clears when Codex continues. Codex chats in the **Chats**
view run without approval prompts, so they never wait.

### opencode

Clusto writes a plugin it owns at `~/.config/opencode/plugins/clusto.js`. Its
first line is `// clusto:managed`; Clusto rewrites the file, so edits are lost.
The plugin:

* reports `permission.asked` and `question.asked` as waiting, with the
  permission or question text as the prompt;
* reports `permission.replied`, `question.replied`, `question.rejected` and
  `session.idle` as idle;
* registers the `clusto` MCP server through opencode's `config` hook, so
  `opencode.jsonc` is never rewritten. A `clusto` MCP entry you wrote yourself
  wins.

A file at that path without the `// clusto:managed` marker is reported as an
error on the AI setup page and left alone. Move it away, then run **Fix now**.

### Gemini CLI

Clusto adds its own hook entries to `~/.gemini/settings.json`, the file that
already holds the `clusto` MCP server:

| Hook | Matcher | Runs |
|---|---|---|
| `Notification` | `ToolPermission` | `clusto internal notify-state --waiting --reason permission` |
| `BeforeTool` | `ask_user` | `clusto internal notify-state --waiting --reason question` |
| `AfterTool` | `ask_user` | `clusto internal notify-state --idle` |
| `BeforeAgent` | - | `clusto internal notify-state --idle` |
| `AfterAgent` | - | `clusto internal notify-state --idle` |

Clusto recognises its entries by their `internal notify-state` command. Your own
hooks are never changed or removed.

### GitHub Copilot CLI

Clusto owns the file `~/.copilot/hooks/clusto.json` (`version` 1):

| Hook | Matcher | Runs |
|---|---|---|
| `notification` | `permission_prompt` | `clusto internal notify-state --waiting --reason permission` |
| `notification` | `elicitation_dialog` | `clusto internal notify-state --waiting --reason question` |
| `postToolUse` | `ask_user` | `clusto internal notify-state --idle` |
| `userPromptSubmitted` | - | `clusto internal notify-state --idle` |
| `agentStop` | - | `clusto internal notify-state --idle` |

Clusto rewrites this file, so edits are lost; put your own hooks in another file
in `~/.copilot/hooks/`. If a file with that name exists and is not Clusto's, the
AI setup check shows an error and the file is left alone. Move it away, then run
**Fix now**.

### Cursor

Cursor has no hook that fires while it waits for you, so Clusto cannot wire it.
Use the copyable instructions under [Works with any AI CLI](#works-with-any-ai-cli).

### Auto-continue after a dropped response

When Claude Code in a Clusto terminal session stops on one of these errors,
Clusto types `continue` and Enter into that terminal for you:

* `API Error: Connection lost mid-response. The response above may be incomplete.`
* `The response stopped arriving`
* `Server error mid-response`
* `Connection lost before a response was produced`
* `Your computer went to sleep mid-response`
* an overloaded API (the `StopFailure` hook above, which runs
  `clusto internal notify-state --failed`)

How it behaves:

* Clusto waits before typing: 2 seconds for a dropped connection, 30 seconds for
  a server error or an overloaded API.
* If you type in that terminal during the wait, the automatic continue is
  cancelled. Plain keys count; focus and mouse reports do not.
* At most 3 automatic continues per session in 10 minutes, so a dead link cannot
  loop. After that the error stays on screen for you to handle.
* Authentication, billing, usage-limit and context errors are never
  auto-continued.
* The node that owns the session decides and types, so it works while the app is
  closed.
* Each scheduled, cancelled or undelivered continue is written to the node log
  (`clusto logs daemon`, search for `auto-continue`), so you can tell afterwards
  whether it fired or your typing cancelled it.

The `StopFailure` hook is written with the other Clusto hooks by the node's AI
setup. Chats are separate: a Claude mid-stream cut in a chat is shown as a
network error on the chat failure card.

### Turning it off

**Knowledge > AI setup > Turn off** on a node removes the Claude Code and Gemini
CLI hooks, the Copilot hooks file and the opencode plugin together with the rest
of the node's AI setup.

## Attention list

The **Attention** view (route `/attention`) is the 7-day
[notification history](/notification-center): the alerts Clusto raised for
agents waiting for an answer, finished turns, task results and new reports, from
every node. It has no tabs. **Mark all read** in the header clears the unread
count and also marks read every unread chat, Azure DevOps item, report and terminal
bell marker (see [Read state](/notification-center#read-state)). Open it with `Mod+Shift+A` (`Ctrl+Shift+A`, or `Cmd+Shift+A` on macOS),
`Mod+I` (outside text fields and terminals), the **bell** in the sidebar header
(on mobile, the bell in the header), the **Attention** entry in the Android menu,
or **Open attention list** or **Open notification history** in the `F1`
palette; all of them open this same page. The bell shows a count of agents
waiting for an answer plus unread notifications.

The **Filter** button in the header chooses which kinds of alert the list shows
and which ones count on the bell and the Attention badge (see
[Choose what to show and count](/notification-center#choose-what-to-show-and-count)).

Each unread row has a check button to mark just that alert read, and a group card
header has a **Mark all in ... read** button that names the group (see
[Read state](/notification-center#read-state)).

Selecting an entry opens the terminal or chat it came from. If an agent never
reports that it waits, run [Node Doctor](#node-doctor) to check that every agent
on every node reports.

## Copy-prompt notification

When a session starts waiting, Clusto can fire a notification carrying the prompt
text the agent set:

* **In-app:** a toast with a **Copy** action that copies the question / prompt
  to your clipboard.
* **App backgrounded:** a native OS alert is shown instead.

If the agent did not pass an explicit prompt, Clusto falls back to the agent's
last message.

On Android, a session that started waiting while the app was fully closed can
still reach you: with [Background Notifications](/background-notifications)
enabled, the app polls the cluster on a ~15 minute timer and raises a native
notification for the waiting state it missed.

## Works with any AI CLI

The `?` marker is tool-agnostic. Claude Code, Codex, opencode, Gemini CLI and
GitHub Copilot CLI are wired for you (see above); any other AI CLI or agent can drive the marker through a small
generic contract.

### The contract

1. **Every command Clusto runs in a terminal** receives the environment variable
   `CLUSTO_SESSION_ID` - the id of the Clusto session the process runs in. You never
   pass ids around; the CLI reads it from the environment.

2. **The tool reports its state** by running the `clusto` CLI:

   When the agent starts waiting for the user:

   ```bash
   clusto internal notify-state --waiting --reason question --prompt "<the question>"
   ```

   * `--reason` is free text, e.g. `question`, `permission`, or `input`.
   * `--prompt` is optional and feeds the notification's **Copy** button. If you
     omit it, Clusto uses the agent's last message.

   When the agent is done / no longer waiting:

   ```bash
   clusto internal notify-state --idle
   ```

3. **Wire it to hooks.** Any tool with a "blocked / waiting" event and a "turn
   finished" event can call `--waiting` on the first and `--idle` on the second.
   Hook payloads arrive as JSON on stdin, and `clusto internal notify-state` also
   reads the `message` / `transcript_path` fields from that JSON when `--prompt`
   is omitted.

For reference, the Claude Code setup Clusto writes is exactly this contract:
`--waiting` on permission and question events, `--idle` on `Stop` and
`UserPromptSubmit`. Do not wire a "finished a turn" idle-prompt event to
`--waiting`, so a finished-but-unanswered turn does not produce a false `?`.

### Without the CLI: OSC 7501

A tool that cannot run the `clusto` CLI (for example over SSH to a machine
without it) can drive the same marker with terminal escape sequences. Print
`ESC ] 7501 ; state=blocked:kind=question:msg=<base64> ST` to show the `?` with a
copyable prompt, and `state=idle` to clear it. See [Terminal Notifications,
Progress and Bell](/terminal-notifications) for the full format and the other
states.

### Requirements

* The `clusto` CLI must be reachable. clustod installs it automatically next to
  itself on startup if missing - no user action needed. For other tools, put it
  on **PATH** or call it by its absolute path.
* Run the commands on the same machine as the session; `CLUSTO_SESSION_ID` is set
  for you automatically.

## Node Doctor

**Settings > Node Doctor** (System group) lists every cluster node with its AI
setup status, including the waiting-status checks above. See
[Node Doctor](/knowledge#node-doctor) for the details. Use **Fix** on a node, or
**Fix all**, to rewrite missing hooks and plugins.

A **This device** row at the top covers the device you are using, so you can see
why a waiting agent did not alert you: system notification permission, alert
popups, alert sound, Android background checks and muted sessions. **Send test
notification** raises a sample alert through the same path a waiting agent uses.

## Settings

The footer of the **Settings > Node Doctor** card has a **Copy setup
instructions** button. Claude Code, Codex, opencode, Gemini CLI and GitHub
Copilot CLI no longer need it: it copies the generic instructions above so you
can hand them to **other tools**, such as Cursor.
To check or repair the automatic setup, use **Settings > Node Doctor**.
