Pular para o conteúdo principal
O ChatCLI implementa um sistema completo de gerenciamento de resultados de ferramentas que garante integridade, controla o tamanho do contexto e compacta resultados antigos progressivamente. Isso e essencial para sessoes longas de agente onde dezenas de tool calls podem saturar a janela de contexto.

​
Pareamento de Tool Results

Toda tool_use (chamada de ferramenta pelo modelo) deve ter um tool_result correspondente no historico de conversacao. Quando essa correspondencia quebra — por interrupcao, timeout ou erro silencioso — a API rejeita o historico. O sistema EnsureToolResultPairing valida e repara automaticamente:
ProblemaAcao de Reparo
tool_use sem tool_result (orfao)Injeta resultado sintetico de erro
tool_result sem tool_use (orfao)Remove do historico
IDs de tool_use duplicadosMantém apenas a primeira ocorrencia

​
Resultados Sinteticos

Quando uma tool_use nao tem resultado correspondente, o ChatCLI injeta: 
[Tool result missing — the tool execution was interrupted or failed silently.
Do NOT retry this tool call. Analyze what went wrong and try a different approach.]
A mensagem instrui o modelo a nao repetir a tool call falha, evitando loops infinitos de retentativa.

​
Validacao em 3 Fases

1

Coleta de IDs

Percorre todo o historico coletando IDs de tool_use (de mensagens assistant) e IDs de tool_result (de mensagens tool).
2

Deteccao de Desalinhamentos

Compara os dois conjuntos de IDs. Tool uses sem resultado sao “missing”. Tool results sem uso sao “orphans”. IDs duplicados sao marcados para dedup.
3

Reconstrucao do Historico

Reconstroi o historico: remove orphans, faz dedup de tool_use IDs e injeta resultados sinteticos apos mensagens assistant com tool_uses sem resultado.

​
Orcamento de Resultados (Budget Enforcement)

Resultados de ferramentas como leitura de arquivos grandes ou saida de comandos podem consumir rapidamente a janela de contexto. O sistema de orcamento limita o tamanho agregado em dois niveis:
NivelLimiteVariavel de AmbienteDefault
Por resultadoTamanho maximo de um unico resultadoCHATCLI_TOOL_RESULT_MAX_CHARS20.000 chars
Por turnoTamanho agregado de todos os resultados no turnoCHATCLI_TOOL_RESULT_BUDGET_CHARS200.000 chars

​
Como Funciona o Enforcement

O orcamento e aplicado em duas passadas:
Cada resultado individual e verificado contra DefaultPerResultMaxChars (20KB). Se exceder, o conteudo completo e salvo em disco e substituido por um preview:
[primeiros 4.000 chars do resultado]

... [85.432 chars omitted — full output saved to /tmp/chatcli-tool-results/budget_tc_1_0.txt]

[ultimos 1.000 chars do resultado]

​
Persistencia em Disco

Resultados truncados sao salvos em arquivos temporarios em /tmp/chatcli-tool-results/: 
/tmp/chatcli-tool-results/
  budget_tc_1_0_1.txt    # Resultado completo da tool call 1
  budget_tc_2_3_2.txt    # Resultado completo da tool call 2
Os arquivos sao limpos automaticamente com CleanupBudgetFiles() ao final da sessao. O modelo pode referenciar o caminho do arquivo no preview se precisar do resultado completo.

​
Preview: Head + Tail

O preview mantem o inicio e o final do resultado para maximizar utilidade:
ComponenteTamanho
Head (inicio)4.000 chars (corta na ultima quebra de linha)
ReferenciaCaminho do arquivo em disco
Tail (final)1.000 chars (corta na primeira quebra de linha)

​
Microcompactacao Progressiva

A microcompactacao reduz progressivamente o tamanho de resultados antigos de ferramentas conforme a conversa avanca, sem perder informacao critica:
Idade do ResultadoAcaoDetalhes
Turno atual e anteriorSem alteracaoResultados preservados integralmente
2+ turnos atrasTruncadoHead (2.000 chars) + tail (500 chars)
4+ turnos atrasResumidoUma linha descritiva: [Old tool result cleared — 450 lines, 28K chars, Go source]

​
Deteccao de Tipo de Conteudo

O resumo identifica automaticamente o tipo do conteudo para contexto:
ConteudoTipo Detectado
Comeca com { ou [JSON
Contem package Go source
Contem def Python source
Contem function JavaScript source
Comeca com diff ou ---diff
Comeca com commit git log
Outrostext

​
Configuracao da Microcompactacao

VariavelDescricaoDefault
CHATCLI_MICROCOMPACT_TRUNCATE_TURNSTurnos antes de truncar2
CHATCLI_MICROCOMPACT_SUMMARIZE_TURNSTurnos antes de resumir4
Apenas resultados com mais de 3.000 chars sao compactados. Resultados pequenos sao sempre preservados. Resultados de ferramentas de escrita e execucao sao preservados por conterem informacoes criticas de erro.

​
Fluxo Completo

O gerenciamento de resultados e aplicado nesta ordem durante o loop do agente: 
1. Tool executa e retorna resultado
2. EnsureToolResultPairing → corrige desalinhamentos
3. EnforceToolResultBudget → trunca resultados grandes
4. ApplyMicrocompact → compacta resultados antigos
5. Historico limpo enviado para a API

​
Configuracao Completa

Variavel de AmbienteDescricaoDefault
CHATCLI_TOOL_RESULT_BUDGET_CHARSOrcamento agregado por turno200.000
CHATCLI_TOOL_RESULT_MAX_CHARSTamanho maximo por resultado20.000
CHATCLI_MICROCOMPACT_TRUNCATE_TURNSTurnos para iniciar truncamento2
CHATCLI_MICROCOMPACT_SUMMARIZE_TURNSTurnos para iniciar sumarizacao4

​
Proximos Passos

Recuperacao de Contexto

O que acontece quando mesmo com orcamento o contexto transborda.

Recuperacao de JSON

Como argumentos malformados sao corrigidos antes da execucao.

Cost Tracking

Monitore o consumo de tokens incluindo tool results.

Modo Agent

O loop ReAct que gera e processa tool calls.