Você mandou /steer para mudar o rumo e tudo congelou: o clarify que travou o turno inteiro

No meio de uma tarefa longa no Slack, o agente para e pergunta: “Continuo limpando os artefatos de build antigos?”. Você não quer responder isso. Mudou de ideia — quer ele no módulo de auth. Então digita /steer deixa os artefatos, olha o auth e aperta Enter.
Aí vem o silêncio.
Nenhum acknowledgement, nenhuma saída nova, a pergunta ainda ali parada. Você espera trinta segundos, manda “tá aí?”, nada. Alguns minutos depois a pergunta some sozinha e o agente segue arrastado — sem qualquer sinal de que viu o seu steer.
Isso não é rede instável nem modelo lento. É um deadlock de verdade, e o motivo é bem específico.
O que o /steer promete de fato
Comece pela semântica, porque o mal-entendido mora aqui.
O /steer não abre um turno novo e não interrompe nada. Ele anexa uma nota à execução que já está em andamento, para o modelo vê-la depois da próxima tool call — a documentação diz exatamente isso: chega depois da próxima tool call, sem interrupção, sem novo turno de usuário. O loop de tool calling não é quebrado; ele só ganha contexto.
Isso é genuinamente útil. O agente está rodando testes, você diz “foca no módulo de auth”, e na iteração seguinte ele se ajusta em vez de recomeçar do zero.
Mas vem com uma premissa: precisa existir uma próxima tool call.
Como o deadlock se forma
Quando o agente pergunta algo no meio da tarefa, a ferramenta que faz a pergunta é o clarify. Ela é diferente das outras: não devolve dado, só espera uma pessoa. No lado do gateway é um prompt pendente — possivelmente um card nativo persistente no Slack ou no Feishu.
Agora empilhe dois fatos:
- A única ferramenta em voo nessa execução é esse
clarify, bloqueado no usuário. - O usuário não respondeu; mandou algo reconhecido como comando (
/steer).
O segundo fato é a armadilha. Um slash command reconhecido deliberadamente não é tratado como resposta ao prompt. Esse design está certo — você queria disparar um comando, não responder à pergunta. Então o prompt continua armado e o clarify continua bloqueado.
O que significa que o lote de ferramentas nunca retorna. Sem próxima fronteira de tool call, sem lugar para o /steer pousar. Pior: o steer é aceito assim mesmo, porque agent.steer() só exige um turno vivo, e o turno está vivo — sentado dentro do clarify. Você recebe uma promessa (“chega depois da próxima tool call”) que nunca poderá ser cumprida.
Antes da correção, a única saída era o agent.clarify_timeout estourar.
A correção: liberar o prompt antes de aceitar o steer
O primeiro commit (fix(gateway): a /steer releases the clarify that owns the turn) faz exatamente isso: no handler do /steer, antes de o steer ser aceito, o prompt pendente é liberado.
A liberação funciona igual ao timeout: o prompt resolve como CANCELLED e um card nativo persistente é aposentado. Com o prompt retirado, o bloqueio some, o turno destravado continua e o steer é drenado na próxima fronteira. O par resolve-plus-retire que antes ficava inline no ramo de prosa virou _release_pending_clarify, compartilhado pelos dois call sites.
E se o modelo encerrar o turno logo depois de ser destravado? O steer não se perde — o finalizer reentrega um steer remanescente como o próximo turno do usuário, então a nota chega, talvez um turno depois.
A segunda armadilha: a ordem importa
Com a primeira correção dentro, sobrou uma corrida mais sutil, e ela merece parágrafo próprio porque explica por que “só trocar duas linhas” virou uma correção separada.
Liberar o prompt destrava a thread do agente imediatamente. Logo em seguida ela espera a atualização de um card — um round trip de rede real no Slack ou no Feishu. A ordem original era: libera o prompt, espera o card atualizar, aceita o steer. Durante esse await, o agente recém-acordado podia disparar a próxima requisição ou terminar o turno por inteiro. Quando o steer era enfileirado, não havia mais turno vivo para injetar, e a nota se perdia.
O segundo commit (fix(gateway): /steer is queued before the clarify it releases wakes the agent) inverte a ordem: enfileira o steer primeiro, depois libera o prompt. Por mais lenta que seja a atualização do card, o steer já está esperando na fila.
Em uma frase: liberar o prompt é o que destrava o turno, e o enfileiramento tem de acontecer antes do destravamento.
O que fazer hoje
Enquanto isso não sai em release (os dois estão na main, não na v0.23.0), há contornos práticos.
Não responda um prompt com um comando. Se o agente está perguntando algo, responda — mesmo que seja “deixa pra depois por enquanto” —, deixe o turno terminar e então use /steer. Ou não faça nada e deixe estourar o timeout.
Saiba qual é o seu timeout. O padrão caiu de uma hora para 90 segundos; configurações antigas podem ainda carregar 3600. Confira o seu valor:
hermes config get agent.clarify_timeout
0 ou um número negativo significa ilimitado (e um clarify.timeout legado no topo, se definido explicitamente, ainda ganha). Se você já aumentou isso pensando em “dar bastante tempo ao usuário”, é exatamente aí que este deadlock machuca mais: uma pergunta sem resposta prende o turno inteiro na mesa.
Quer se intrometer sem tomar o turno? Use /btw. É o canal de aparte: responde uma pergunta paralela sem interromper o trabalho em andamento e não transforma a sua mensagem num comando que perturba o prompt pendente. Veja fazendo uma pergunta paralela com /btw.
Faça menos perguntas de antemão. Se você precisa esclarecer cinco coisas, peça em um lote só em vez de cinco idas e voltas — o padrão está em clarify com perguntas em lote.
O que o bug está de fato dizendo
Na superfície é um bug de ordenação de duas linhas. A parte interessante são as três premissas que ele quebrou:
Primeira, o /steer assume que sempre existe uma próxima fronteira de ferramenta. Isso vale enquanto as ferramentas retornam sozinhas — mas o clarify é a única cuja condição de retorno é um humano, e ela quebra a premissa.
Segunda, o roteamento de comandos assume que um comando não precisa do turno. Quase sempre verdade: a maioria dos slash commands lê ou grava config e troca de modo. O /steer é um dos poucos que precisa do turno para fazer efeito.
Terceira, e essa é a que vale levar para o seu próprio código: destravar é um ato com efeito colateral. Separe isso da entrega e o await entre os dois vira uma nova janela de corrida. Ou entregue antes de destravar, ou torne o par atômico — aqui a opção mais barata foi reordenar, porque trocar duas linhas custa menos do que construir uma transação.
Se você orquestra vários agentes, ou usa /steer para corrigir um subagente, a mesma fronteira comando-versus-resposta aparece em outros lugares; as notas sobre sinais de controle em orquestração ao vivo de subagentes e a referência de hermes gateway do site cobrem o lado do roteamento.
Status
Os dois commits estão na main (7 de novembro) e em nenhuma tag, v0.23.0 inclusive. hermes update traz releases, então você só terá essa correção na próxima — ou acompanhe a main.
Atualização (10/11/2026): essas mudanças saíram na v0.23.1 (9 de novembro): basta um
hermes update. O « não está na v0.23.0 » acima continua correto; a v0.23.1 fecha a lacuna.
Até lá, o conselho mais curto já basta: quando o agente está esperando uma resposta, não responda a pergunta dele com um comando.