API pública de ciclo de vida de subagentes

Plugins conseguem abrir e supervisionar sessões filhas novas do Hermes sem importar tools.delegate_tool, internals do gateway, estado da TUI ou campos de AIAgent. O serviço descobre o pai a partir do turno de agente em andamento, então funciona em sessões de CLI, de gateway, não interativas e de trabalhador do kanban. Abrir fora de um turno ativo falha fechado, com No active Hermes parent session.

from agent.subagent_lifecycle import SubagentLaunchRequest

def launch_review(ctx):
    # Chame de uma ferramenta ou hook de plugin, com um turno de agente ativo.
    service = ctx.subagent_lifecycle
    handle = service.launch(SubagentLaunchRequest(
        goal="Review this change for regressions.",
        context="Only inspect the supplied repository.",
        role="leaf",
        correlation_id="review-42",
        allowed_toolsets=("file",),
    ))
    # Se quiser, persista handle.to_dict().
    if service.wait(handle, timeout_seconds=2).timed_out:
        return handle.to_dict()
    return service.result(handle)

O SubagentHandle é serializável e carrega uma capacidade opaca e versionada. Devolva-o para status, wait, cancel, result ou reconnect; identificadores malformados ou forjados devolvem UNKNOWN ou UNKNOWN_HANDLE e não conseguem acessar um filho.

Os estados estáveis são PENDING, STARTING, RUNNING, SUCCEEDED, FAILED, INTERRUPTED, CANCEL_REQUESTED, CANCELLED e UNKNOWN.

O cancel(handle, reason=...) é cooperativo: pede ao agente filho para interromper no próximo ponto seguro e devolve CANCEL_REQUESTED; ele nunca afirma conclusão até que wait ou result observem um estado terminal. Resultados terminais são imutáveis, idempotentes, limitados a 32 mil caracteres, omitem transcrições e raciocínio oculto, e trazem um hash estável do resultado.

Esta API é execução assíncrona com ciclo de vida gerenciado. A construção e a conclusão do filho usam o mesmo caminho do delegate_task, incluindo restauração da resolução de ferramentas do pai, notificação de memória, hooks subagent_stop serializados, limpeza de recursos e consolidação do custo do filho. Ela não muda a ferramenta síncrona delegate_task, a delegação em lote, nem a exibição no gateway e na TUI. A implementação inicial guarda metadados e resultados terminais em processo por uma hora.

Depois de reiniciar o processo, o reconnect devolve RECONNECT_UNAVAILABLE e nunca abre um filho substituto. Threads Python em execução também não sobrevivem à saída do processo; quem chama deve tratar esses identificadores como interrompidos pela saída.

As requisições falham fechado: tamanhos de objetivo, contexto e metadados têm teto; conjuntos de ferramentas desconhecidos ou que ampliem o do pai são recusados; e bloqueios por ferramenta, sobrescrita de diretório de trabalho e tempo limite por lançamento são recusados explicitamente, até o Hermes conseguir suportá-los sem enfraquecer o isolamento. Use allowed_toolsets para estreitar um filho; o bloqueio de ferramentas inseguras que já existe continua valendo.