HAOS Model Router

Autor: Gian Marco Menegussi Scaglianti. Decisao permanente do dono do projeto.

Principio (nao negociavel)

1. Qualidade primeiro. O objetivo e a tarefa sair CERTA na primeira vez.
2. Custo-beneficio segundo. Dentro do que entrega qualidade, escolher o mais barato.
3. Economia nunca por si so. Nao existe "usar haiku pra poupar" quando a tarefa pede julgamento.
4. Na duvida entre dois tiers, SOBE. Retrabalho, decisao errada ou mensagem externa errada custa muito mais que a diferenca de token.
5. O main (orquestrador) fica no modelo da sessao. O router decide o modelo dos SUB-AGENTES, nao o do main.

Matriz por tipo de tarefa

Regra de effort (Workflow)

O parametro effort (low / medium / high / xhigh / max) e ortogonal ao modelo.

• Mecanico e deterministico: low.
• Trabalho padrao (codigo, analise, doc): medium.
• Verificacao, juizo, decisao, sintese final: high ou acima.
• Nunca economizar effort em fase de verificacao. E exatamente ali que a economia custa caro.

Composicao em Workflow

• Fase mecanica DESCE (haiku/sonnet, effort low/medium).
• Fase de verificacao, decisao ou sintese SOBE (opus/fable, effort high+).
• Declarar model explicitamente em CADA agent() do script e em cada item de meta.phases.
• Workflow sem model declarado = roteamento por acaso. Nao aceitar.

Como declarar

• Ferramenta Agent: parametro model OBRIGATORIO, valor em haiku | sonnet | opus | fable.
• No briefing do sub-agente, incluir uma linha: MODELO: <tier> porque <motivo em 1 frase>
• Ao spawnar, o main mostra ao dono essa mesma linha, curta, sem enrolacao. Uma linha por agente.

Exemplo:

MODELO: opus porque e causa raiz de bug intermitente em producao, nao rotina.
MODELO: haiku porque e varredura de arquivo com criterio ja fechado.

Anti-padroes (nao fazer)

• haiku em tarefa que exige julgamento, trade-off ou juizo de qualidade.
• fable em grep, listagem ou conversao de formato.
• Economizar tier na fase de VERIFICACAO de qualquer pipeline.
• Spawnar Agent sem declarar model (o guard model_guard.py bloqueia).
• Escolher tier "porque a sessao ja estava nele". Herdar nao e decidir.
• Descer tier em tarefa que gera gasto, envio externo ou alteracao irreversivel.

Trava fisica

O hook PreToolUse model_guard.py bloqueia qualquer chamada de Agent feita pelo MAIN dentro do escopo protegido sem model valido declarado. Sub-agentes nao sao afetados. Workflow nao e bloqueado pelo hook (o script e texto); a disciplina ali vem do GATE MODELO injetado a cada prompt pelo prompt_router.py e desta skill.

Tarifa de spawn

Decisao do dono do projeto, tomada apos um conclave interno sobre quando o orquestrador deve executar direto e quando deve delegar.

O fato que gerou a regra. Spawn nao e gratis e o custo NAO e proporcional a tarefa: o boot do sub-agente domina. Piso medido de um spawn: 88k tokens e 1 minuto. Mediana: 183k tokens e 8,3 minutos. Nesta semana, 5 spawns triviais custaram 678k tokens contra 10-40k se o main tivesse feito na mao: 94% a 99% de desperdicio. Escolher tier certo (secao acima) resolve metade do problema; a outra metade e nao pagar boot por nada.

Matriz: quando spawnar x quando NAO spawnar

Regra de bolso: o spawn tem que comprar alguma coisa que o main nao tem - especialidade, volume que queimaria contexto, paralelismo, ou uma trava fisica. Se ele so repete o que o main faria, voce pagou 88k de boot por nada.

Este pacote nao inclui um regime de "cota de mutacao trivial" para o orquestrador: toda mutacao fora da allowlist de leitura pura vai para sub-agente (Regra de Ouro, ver docs). Se voce quiser um regime de cota, e uma extensao que voce escreve por cima deste guard, nao algo que este pacote traz pronto.

Modelo por classe (com as metas do piloto)

Mix medido em 03-06/09/2026: opus 67%, haiku 2,5%. Isso e roteamento por inercia, nao decisao. As metas medem o MIX ao longo da semana, nao a tarefa isolada: "na duvida entre dois tiers, SOBE" (Principio 4) continua valendo caso a caso e vence a meta quando os dois conflitam. A meta nao autoriza descer tier em tarefa que pede julgamento; ela cobra que o mecanico DESCA.

Briefing enxuto (teto de 6 linhas)

Briefing de 3 paginas e a forma mais cara de pagar boot duas vezes: o texto entra no contexto do sub-agente inteiro, e o que ele precisava era o caminho.

OBJETIVO: <1 frase, o resultado esperado>
DADOS: <caminho absoluto do artefato / comando que produz o dado>   # NUNCA colar relatorio inteiro
FORMATO: <o que voltar: tabela, diff, lista de caminhos, veredito>
RESTRICOES: <o que NAO tocar, arquivos de outro agente, nada de push/envio>
MODELO: <tier> porque <motivo em 1 frase>
LASTRO: toda causa/estado/mecanismo com [verifiquei: <comando> -> <o que vi>]; o resto [hipotese]

Se um artefato precisa ir de um agente para outro, vai pelo DISCO: grave e passe o caminho (skill haos-handoff-artefato, gate no hook handoff_guard). Resumo do main no meio do caminho apaga evidencia e ainda custa token nas duas pontas.

Reuso: SendMessage antes de spawn novo

Agente ja aberto se retoma com SendMessage (pelo id ou nome), e ele mantem o contexto dele - verificado em uso nesta sessao: 5 retomadas de agente sem perder estado. Spawn novo paga o boot inteiro de novo e comeca do zero, sem o que ele ja descobriu.

Antes de spawnar, a pergunta e: "ja tem alguem aberto que sabe disso?" Se tem, SendMessage. ListAgents mostra quem esta vivo.

Onde o main pode trabalhar sem pagar nada

O scratchpad da sessao e livre para o main (arquivo temporario, resultado intermediario, script de apoio, dado bruto de analise). Escrever ali nao e "executar tarefa de squad", e memoria de trabalho - nao existe motivo para spawnar um agente so para criar um arquivo temporario.

Anti-padroes de tarifa (somam aos anti-padroes de tier acima)

• Spawnar para ler UM arquivo cujo caminho o main ja conhece.
• Spawnar para conferir algo que o main acabou de ver na tela neste mesmo turno.
• Spawnar opus para inventario ou listagem (e haiku; era 67% do mix).
• Colar o relatorio inteiro do agente A no briefing do agente B, em vez do caminho do artefato.
• Abrir agente NOVO para continuar o trabalho de um agente que ainda esta vivo.
• Spawnar sub-agente para um passo que so o main consegue fazer (MCP, browser) - ele volta BLOQUEADO e o boot foi perdido.
• Usar "na duvida, DELEGUE" como desculpa para o trivial: a frase vale para ESPECIALIDADE, VOLUME, PARALELISMO e ACAO EXTERNA, nunca para as 5 leituras que o main faz em 30 segundos.