Le mandaste /steer para cambiar de rumbo y se quedó congelado: el clarify que bloqueó el turno entero


A mitad de una tarea larga en Slack, el agente se para y pregunta: «¿Sigo limpiando los artefactos de build antiguos?». No quieres responder eso. Has cambiado de idea: ahora lo quieres en el módulo de auth. Así que escribes /steer skip the artifacts, look at auth y pulsas Enter.

Y entonces: silencio.

Sin acuse, sin salida nueva, la pregunta todavía ahí. Esperas treinta segundos, mandas «¿estás ahí?», nada. Unos minutos después la pregunta desaparece sola y el agente sigue a lo suyo, sin ninguna señal de haber visto tu steer.

Esto no es red inestable ni un modelo lento. Es un deadlock de verdad, y la causa es muy concreta.

Qué promete realmente /steer

Empecemos por la semántica, porque el malentendido vive justo aquí.

/steer no arranca un turno nuevo ni interrumpe. Añade una nota al run que ya está en marcha, para que el modelo la vea después de la siguiente llamada a herramienta; la documentación lo dice tal cual: llega tras la siguiente tool call, sin interrupción, sin un nuevo turno de usuario. El bucle de tool calling no se rompe: solo gana contexto.

Eso es genuinamente útil. El agente está corriendo tests, le dices «céntrate en el módulo de auth», y en su siguiente iteración se ajusta en vez de empezar de cero.

Pero viene con una suposición: tiene que haber una siguiente llamada a herramienta.

Cómo se forma el deadlock

Cuando el agente te pregunta algo a mitad de tarea, la herramienta que pregunta es clarify. No se parece a las demás: no devuelve datos, solo espera a una persona. En el lado del gateway es un prompt pendiente, posiblemente una tarjeta nativa persistente en Slack o Feishu.

Ahora apila dos hechos:

  1. La única herramienta en vuelo en este run es ese clarify, bloqueado esperando al usuario.
  2. El usuario no ha respondido: ha mandado algo que se reconoce como comando (/steer).

El segundo hecho es la trampa. Un comando slash reconocido no se trata como respuesta al prompt, y eso es deliberado. El diseño es correcto: querías lanzar un comando, no contestar la pregunta. Así que el prompt sigue armado y el clarify sigue bloqueado.

Lo que significa que el batch de herramientas no vuelve nunca. Sin siguiente frontera de tool call, no hay dónde aterrice el /steer. Y peor: el steer se acepta igualmente. agent.steer() solo exige un turno vivo, y el turno está vivo, sentado dentro del clarify. Así que te dan una promesa («llega tras la siguiente llamada a herramienta») que no se puede cumplir jamás.

Antes del fix, la única salida era que expirase agent.clarify_timeout.

El fix: liberar el prompt antes de aceptar el steer

El primer commit (fix(gateway): a /steer releases the clarify that owns the turn) hace exactamente eso: en el handler de /steer, antes de aceptar el steer, se libera el prompt pendiente.

Liberar funciona igual que el timeout: el prompt se resuelve como CANCELLED y una tarjeta nativa persistente se retira. Con el prompt retirado el bloqueo desaparece, el turno desbloqueado continúa y el steer se drena en la siguiente frontera. El par resolver-más-retirar que estaba inline en la rama de prosa pasó a ser _release_pending_clarify, compartido por ambos call sites.

¿Y si el modelo cierra el turno justo después de desbloquearse? El steer no se pierde: el finalizer reentrega un steer sobrante como siguiente turno de usuario, así que la nota llega, quizá un turno más tarde.

La segunda trampa: el orden importa

Con el primer fix dentro quedaba una carrera más sutil, y merece su propio párrafo porque explica por qué «solo cambiar dos líneas» necesitó un fix aparte.

Liberar el prompt desbloquea el hilo del agente de inmediato. Justo después se espera una actualización de tarjeta: un round trip de red real en Slack o Feishu. El orden original era: liberar el prompt, esperar la actualización de la tarjeta y luego aceptar el steer. Durante ese await, el agente recién despierto podía lanzar su siguiente petición o terminar el turno del todo. Para cuando el steer se encolaba, ya no había turno vivo donde inyectarlo, y la nota se había ido.

El segundo commit (fix(gateway): /steer is queued before the clarify it releases wakes the agent) invierte el orden: encolar el steer primero, liberar el prompt después. Por lenta que sea la actualización de la tarjeta, el steer ya está esperando en la cola.

En una frase: liberar el prompt es lo que desbloquea el turno, y encolar tiene que pasar antes de desbloquear.

Qué hacer mientras tanto

Hasta que esto llegue a una release (los dos están en main, no en la v0.23.0), hay apaños prácticos.

No respondas a un prompt con un comando. Si el agente está preguntando algo, contéstale —aunque sea «déjalo por ahora»—, deja que el turno termine y luego usa /steer. O no hagas nada y deja que expire.

Conoce tu timeout. El valor por defecto bajó de una hora a 90 segundos; configuraciones antiguas pueden seguir arrastrando 3600. Comprueba el tuyo:

hermes config get agent.clarify_timeout

0 o un número negativo significa ilimitado (y un clarify.timeout heredado de nivel superior, si está puesto explícitamente, sigue ganando). Si en su día lo subiste para «dar tiempo a los usuarios», es justo donde este deadlock duele más: una pregunta sin responder clava el turno entero en el escritorio.

¿Quieres meter baza sin quedarte con el turno? Usa /btw. Es el canal aparte: responde una pregunta lateral sin interrumpir el trabajo en curso y no convierte tu mensaje en un comando que perturbe el prompt pendiente. Mira preguntar algo de lado con /btw.

Pregunta menos cosas por adelantado. Si necesitas aclarar cinco cosas, pídelas en un solo lote en vez de cinco idas y venidas; el patrón está en preguntas de clarify en lote.

Qué te está diciendo el bug de verdad

En la superficie es un bug de orden de dos líneas. Lo interesante son las tres suposiciones que rompió:

Primero, /steer asume que siempre hay una siguiente frontera de herramienta. Se cumple mientras las herramientas vuelven solas, pero clarify es la única herramienta cuya condición de retorno es una persona, y ahí la suposición se rompe.

Segundo, el enrutado de comandos asume que un comando no necesita el turno. Casi siempre es cierto: la mayoría de los comandos slash leen o escriben config y cambian de modo. /steer es de los pocos que necesitan el turno para tener efecto.

Tercero, y esta es la que llevarte a tu propio código: desbloquear es un acto con efectos secundarios. Sepáralo de la entrega y el await entre ambos se convierte en una nueva ventana de carrera. O entregas antes de desbloquear, o haces atómico el par; aquí la opción barata fue reordenar, porque cambiar dos líneas cuesta menos que montar una transacción.

Si orquestas varios agentes, o usas /steer para corregir a un subagente, esa misma frontera entre comando y respuesta aparece en otros sitios; las notas sobre señales de control en orquestación en vivo de subagentes y la referencia de hermes gateway del sitio cubren el lado del enrutado.

Estado

Los dos commits están en main (7 de noviembre) y en ninguna etiqueta, la v0.23.0 incluida. hermes update te da releases, así que no tendrás este fix hasta la siguiente, o sigue main por tu cuenta.

Actualización (10/11/2026): estos cambios ya salieron en la v0.23.1 (9 de noviembre): basta con hermes update. Lo de «no está en v0.23.0» sigue siendo cierto; la v0.23.1 cierra la brecha.

Hasta entonces el consejo más corto basta: cuando el agente está esperando una respuesta, no contestes a su pregunta con un comando.