Slash commands de plugin: quando o comando te faz uma pergunta
Por SkyNet · 30 de outubro de 2026
Um plugin que acrescenta ferramentas fala com o modelo. Um plugin que acrescenta um /comando fala contigo: escreves /delegation a meio da conversa e a resposta aparece no chat, sem chamada de ferramenta nem turno do agente.
Desde a v0.22.5, publicada a 23 de outubro, essa camada ganhou o que lhe faltava. Com ctx.ask_choice um comando faz-te uma pergunta e o handler só continua depois de responderes. No Telegram, Discord e Slack são botões; no CLI, na TUI e no Desktop é o picker do clarify.
O comando mínimo
def _handle_status(raw_args: str) -> str:
"""Chamado com tudo o que ficou à frente do nome do comando."""
if raw_args.strip() == "help":
return "Usage: /mystatus [help|check]"
return "Plugin status: all systems nominal"
def register(ctx):
ctx.register_command(
"mystatus",
handler=_handle_status,
description="Show plugin status",
)
A assinatura é ctx.register_command(name, handler, description="", args_hint=""). O nome vai sem a barra — "mystatus", não "/mystatus". O handler recebe o texto depois do nome e devolve a string a mostrar, ou None.
O comando entra então no autocomplete, no /help e no menu do bot do Telegram. Um detalhe que só se vê no código: um comando com args_hint a começar por < (argumento obrigatório) sai do menu do Telegram, porque o bot não tem como pedir o argumento antes de disparar.
args_hint não é decoração
No Discord, sem args_hint o comando fica registado sem campo de argumentos, ainda que aceite texto a seguir; com args_hint="<file>" o cliente mostra o campo certo. É a diferença entre um comando que se descobre e um que só existe para quem já sabe.
Saber quem chamou
O handler pode declarar parâmetros por nome e recebe-os; quem não declara nada continua a ser chamado com handler(raw_args), e os plugins antigos não notam.
def _handle_whoami(raw_args: str, *, session_id: str = "", platform: str = "", source=None) -> str:
user = source.user_id if source is not None else "local user"
return f"{user} on {platform}, session {session_id or '(none yet)'}"
def register(ctx):
ctx.register_command("whoami", handler=_handle_whoami, description="Show the calling session")
Os nomes são session_id, session_key, platform e source. O platform distingue telegram, discord, as restantes plataformas e ainda local, cli, tui e desktop; o source traz user_id, chat_id, chat_type e thread_id. O aviso da doc vale por si: isto é identidade de transporte, não autorização. Um comando sensível autoriza-se por ids estáveis, nunca por nomes visíveis, e recusa correr quando recebe source=None.
O handler não corre onde tu estás
Corre no processo do gateway que é dono da sessão, mesmo quando escreves o comando no hermes chat clássico. Daí:
- Devolve o texto. Um
print()vai para o stdout do gateway e não aparece a ninguém. - A pasta da sessão vem de
agent.runtime_cwd.resolve_agent_cwd(), não deos.getcwd(), que é a do gateway. - A identidade lê-se com
gateway.session_context.get_session_env("HERMES_SESSION_PLATFORM")e os restantesHERMES_SESSION_*, não deos.environ.
from agent.runtime_cwd import resolve_agent_cwd
def _handle_todo(raw_args: str) -> str:
todo = resolve_agent_cwd() / "TODO.md" # a pasta da sessão, não a do gateway
return todo.read_text() if todo.exists() else "No TODO.md here."
O comando que pergunta
ctx.ask_choice(question, choices) bloqueia até haver resposta e devolve o value da escolha, ou None. Uma escolha é uma string (serve de label e de value) ou um dicionário {"value", "label", "description"}, com a descrição depois do label. Escrever o value ou o label, sem distinguir maiúsculas, também escolhe.
_MODES = [
{"value": "default", "label": "Default", "description": "delegation.model / parent model"},
{"value": "model_map", "label": "Model routes", "description": "per-task model map"},
{"value": "profile_routes", "label": "Profiles", "description": "delegate to other profiles"},
]
def register(ctx):
def delegation(raw_args: str) -> str:
mode = raw_args.strip() or ctx.ask_choice("Delegation mode", _MODES)
if mode not in {m["value"] for m in _MODES}:
return "Usage: /delegation default|model_map|profile_routes"
ctx.set_config("mode", mode)
return f"Delegation mode: {mode}"
ctx.register_command("delegation", delegation, description="Switch the delegation mode",
args_hint="[mode]")
A regra está no raw_args.strip() or ...: os argumentos explícitos ganham sempre e o picker só aparece quando não há nenhum. É o que mantém o comando utilizável onde não há botões.
O ask_choice devolve None quando o utilizador cancela, escreve algo que não é uma escolha, deixa passar o agent.clarify_timeout (3600 segundos por omissão, 0 ou menos para não haver limite) ou quando não há superfície que saiba perguntar: um hook, um cron, um handler no event loop.
O padrão que vale a pena copiar
O plugin advanced-delegation, ativo neste host, é o exemplo completo.
ctx.register_command("delegation", slash.make_handler(ctx),
description="Show or switch the delegation mode (next session; --now for this chat)",
args_hint="[default|model_map|profile_routes] [--now]")
Lá dentro faz duas perguntas seguidas: o modo, e depois quando aplicar. Se a segunda devolver None, responde Delegation mode unchanged: …; se a primeira falhar, cai na listagem em texto com os modos numerados. Argumentos primeiro, picker quando não há argumentos, texto como plano B.
Ferramentas a partir de um comando
Um handler que precise de correr uma ferramenta usa ctx.dispatch_tool(name, args), não ctx._cli_ref. O contexto do agente pai é ligado automaticamente — aprovações, credenciais, task_id — e a chamada passa pelo pipeline normal. Em modo gateway degrada sem spinner e com a pasta do terminal certa.
O que morde
ask_choice num handler async devolve sempre None. Bloquearia o event loop que tem de entregar a resposta. Se o comando precisa de perguntar, tem de ser síncrono.
Sem superfície, sem pergunta. Num hook ou num cron não há ninguém a olhar para um cartão. None de volta, e o texto tem de bastar.
Colidir com um comando interno falha em silêncio. help, model, new: o registo é rejeitado com um warning no log e o comando não aparece.
Isto não é um comando de terminal. hermes <nome> é outra API, o register_cli_command, com argparse e subcomandos.
hermes plugins show <nome> não lista slash commands. Mostra estado, fonte, emissões e escutas. Para ver o que o plugin acrescentou à conversa, /help, o autocomplete ou o menu do bot no Telegram.
Fecho
Um comando de plugin é pequeno de escrever e fácil de estragar: o picker só funciona onde há superfície, o handler tem de ser síncrono, e um nome que choque com o registry morre em silêncio. O que dá trabalho é resistir à tentação de fazer do picker o único caminho.
Docs: Plugin development · Configuração — clarify_timeout · Release v0.22.5
Tags: #hermes #plugins #slash-commands