claude-cluster docs1.10.1
Advanced conceptsConcepts avancés

Callbacks, questions and the MCPRappels, questions et MCP

How answers come back, how the agents' questions are handled, the MCP server and its settings page.Comment les réponses reviennent, comment les questions des agents sont traitées, le serveur MCP et sa page de réglages.

1. CallbacksRappels

Nothing in claude-cluster polls. When the global session sends a prompt (session_send, session_spawn, a task, a job) the result comes back to it as a message it can read:

MessageWhen
[reply from <name> (<id>)] ...a sub-session finished the turn started for the global session
[reply from ...] with a notea later turn the agent started by itself, when a background task completes - or claude-cluster woke it with the <task-notification> of its command done or killed, a [job ...] / [tasks] result: its real result after a "waiting for my build" answer (that answer noted "its background still runs"). A background task ending during another turn (the user's, a keep-warm wake-up) makes the end of that turn its result, told the same way
[closed: ...] / [stopped: ...]the session was closed before it answered / its agent stopped: no answer will come. [stopped: ...] also comes after the answer when something ran in the background, and names what stopped with it
[status from <name> (<id>)] ...a sub-session telling something now, before the end of its turn (its tool report_status, one every 30 s)
[error from ...]an API error (a limit, the weekly limit...)
[interrupted: ...]an interrupted turn or an agent that exited
[job jN finished|failed|killed]a job added by jobs_add, with exit code, duration, tail
[tasks] ...the result of a task, to the sub-session that queued it
[form "<title>" (<id>) filled by the user] {...}a display form you submitted

The callback owed goes with its turn: a turn of the user ending while the prompt of the global session waits in the queue is not its answer. It is not dropped when the session told is away for a moment (starting again): tried for two minutes, then a notice. A shell or an agent of the background that ends or is killed is also a line of the conversation, its last output kept in its log (F7), even when no model says anything about it.

What no session can tell (a process outside, a deploy, a time) has its own wake-up: task_add with on_event and schedule_add; the system prompts tell the agents to ask for one rather than promise to look later. The end of a turn woken that way (a schedule, a task a session queued for itself) goes to whoever follows the session, like a background task done.

reply: false opts out of a callback. The tests callbacks.sh, send_prompt.sh and callbacks_background.py check the behaviour with a fake claude.

Rien dans claude-cluster n'interroge en boucle. Quand la session globale envoie un prompt (session_send, session_spawn, une tâche, un travail), le résultat lui revient sous forme d'un message qu'elle peut lire :

MessageQuand
[reply from <nom> (<id>)] ...une sous-session a fini le tour lancé pour la session globale
[reply from ...] avec une noteun tour ultérieur que l'agent a lancé lui-même, quand une tâche d'arrière-plan se termine - ou que claude-cluster l'a réveillé avec la <task-notification> de sa commande finie, un résultat [job ...] / [tasks] : son vrai résultat après une réponse « j'attends mon build » (cette réponse notée « its background still runs »)
[closed: ...] / [stopped: ...]la session a été fermée avant de répondre / son agent s'est arrêté : aucune réponse ne viendra
[error from ...]une erreur d'API (une limite, la limite hebdomadaire...)
[interrupted: ...]un tour interrompu ou un agent qui s'est arrêté
[job jN finished|failed|killed]un travail ajouté par jobs_add, avec code, durée, fin de sortie
[tasks] ...le résultat d'une tâche, à la sous-session qui l'a mise en file
[form "<titre>" (<id>) filled by the user] {...}un formulaire d'affichage que vous avez envoyé

Le rappel dû va avec son tour : un tour de l'utilisateur qui se termine pendant que le prompt de la session globale attend dans la file n'est pas sa réponse. Il n'est pas perdu quand la session prévenue est absente un instant (elle redémarre) : retenté pendant deux minutes, puis une notice. Un shell ou un agent d'arrière-plan qui se termine ou qui est tué est aussi une ligne de la conversation, sa dernière sortie gardée dans son journal (F7), même si aucun modèle n'en dit rien. Une tâche d'arrière-plan qui se termine pendant un autre tour (celui de l'utilisateur, un réveil de keep warm) fait de la fin de ce tour son résultat ; [stopped: ...] vient aussi après la réponse quand quelque chose tournait en arrière-plan, et nomme ce qui s'est arrêté avec l'agent ; [status from <nom> (<id>)] ... : une sous-session qui dit quelque chose maintenant, avant la fin de son tour (son outil report_status, un toutes les 30 s).

Ce qu'aucune session ne peut dire (un processus extérieur, un déploiement, une heure) a son propre réveil : task_add avec on_event et schedule_add ; les prompts système disent aux agents d'en demander un plutôt que de promettre de regarder plus tard. La fin d'un tour réveillé ainsi (une planification, une tâche qu'une session s'est donnée) va à ceux qui suivent la session, comme une tâche d'arrière-plan terminée.

reply: false désactive un rappel. Les tests callbacks.sh et send_prompt.sh vérifient le comportement avec un faux claude.

2. Questions of the agentsQuestions des agents

An agent can ask a question (AskUserQuestion of Claude Code, even in bypassPermissions). It shows as a popup on the session shown, in every interface: one question at a time with its options, 1-9 to pick, Enter to validate, Other to type, Esc to decline; several choices tick with Enter or Space, and a Next → row after Other (Review → / Submit → on the last question, like Claude Code) goes on with the ticks kept. What is written on Other stays without Enter, in every interface: an arrow away, another question and back, the page drawn again; it is an answer once validated.

  • One at a time for the whole cluster, shared by keys, mouse, voice and web page. The question of a sub-session is shown on the global session ([sessions] questions_to_global, on) with the sub-session's own view greyed.
  • Review: after the last question every answer is shown on one page: Submit, Cancel, or back to edit.
  • Chat about this (Ctrl+T, a button, a field): talk about the question with the model of the session without touching its conversation (no fork, no resume), shared by the interfaces.
  • The global session answers for you when you press Ctrl+G (terminal), Global answers (window, web page, notification) or say la globale: it chooses from the conversation, the project and the map of your computer and tells you what it answered. [sessions] global_answers (off) lets it be told the questions and choose by itself.
  • By voice: a number or the label of an option, next, back, other ..., cancel.

The safety check of Claude Code (a removal it cannot resolve) can only be approved by a person: a sub-session in bypassPermissions asks the global session (bypass_to_global, on), which asks you when unsure.

Un agent peut poser une question (AskUserQuestion de Claude Code, même en bypassPermissions). Elle s'affiche en fenêtre sur la session montrée, dans toutes les interfaces : une question à la fois avec ses options, 1-9 pour choisir, Entrée pour valider, Other pour taper, Échap pour décliner ; plusieurs choix se cochent avec Entrée ou Espace, et une ligne Next → après Other (Review → / Submit → sur la dernière question, comme Claude Code) passe à la suite en gardant les coches. Ce qui est écrit dans Other reste sans Entrée, dans chaque interface : une flèche ailleurs, une autre question et retour, la page redessinée ; ce n'est une réponse qu'une fois validé.

  • Une à la fois pour tout le cluster, partagée par touches, souris, voix et page web. La question d'une sous-session s'affiche sur la session globale ([sessions] questions_to_global, activé) avec la vue propre de la sous-session grisée.
  • Revue : après la dernière question toutes les réponses s'affichent sur une page : Submit, Cancel, ou retour pour corriger.
  • Chat about this (Ctrl+T, un bouton, un champ) : discuter de la question avec le modèle de la session sans toucher à sa conversation (ni fork, ni reprise), partagé par les interfaces.
  • La session globale répond à votre place quand vous appuyez sur Ctrl+G (terminal), Global answers (fenêtre, page web, notification) ou dites la globale : elle choisit d'après la conversation, le projet et la carte de votre ordinateur et vous dit ce qu'elle a répondu. [sessions] global_answers (désactivé) lui fait connaître les questions et choisir seule.
  • À la voix : un numéro ou le libellé d'une option, next, back, other ..., cancel.

Le contrôle de sécurité de Claude Code (une suppression qu'il ne sait pas résoudre) ne peut être approuvé que par une personne : une sous-session en bypassPermissions le demande à la session globale (bypass_to_global, activé), qui vous demande en cas de doute.

3. The MCP serverLe serveur MCP

The global session has the MCP server claude-cluster mcp, whose tools are listed in the MCP tools reference (generated from the code). A sub-session of the claude driver gets a smaller one (task_*, schedule_*, job tools) scoped to what it created.

Settings > MCP (F9 > MCP) lists every tool with what it does and an on / off switch ([mcp_tools] <tool> = false: refused at once with a message, left out of its tool list at its next start), and the custom MCP servers it gets too ([mcp] servers: "name: command args" for a local program or "name: https://url"), written in its MCP config at its next start. Adding a server is a protected setting, confirmed at save.

The tools are allowed without a prompt (--allowedTools mcp__claude-cluster); what they may do is bounded: see Security.

La session globale dispose du serveur MCP claude-cluster mcp, dont les outils sont listés dans la référence des outils MCP (générée depuis le code). Une sous-session du pilote claude en reçoit un plus petit (task_*, schedule_*, outils de travaux) limité à ce qu'elle a créé.

Réglages > MCP (F9 > MCP) liste chaque outil avec ce qu'il fait et un interrupteur ([mcp_tools] <outil> = false : refusé aussitôt avec un message, absent de sa liste d'outils à son prochain démarrage), et les serveurs MCP personnalisés qu'elle reçoit aussi ([mcp] servers : "nom: commande args" pour un programme local ou "nom: https://url"), écrits dans sa config MCP à son prochain démarrage. Ajouter un serveur est un réglage protégé, confirmé à la sauvegarde.

Les outils sont autorisés sans demande (--allowedTools mcp__claude-cluster) ; ce qu'ils peuvent faire est borné : voir Sécurité.

4. The docs toolL'outil docs

The tool docs lets the global session search this documentation or open a page for you (search, page, open). See the MCP tools reference.

L'outil docs permet à la session globale de chercher dans cette documentation ou d'ouvrir une page pour vous (search, page, open). Voir la référence des outils MCP.