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 sessões 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 histórico de conversacao. Quando essa correspondencia quebra — por interrupcao, timeout ou erro silencioso — a API rejeita o histórico. 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 histórico
IDs de tool_use duplicadosMantém apenas a primeira ocorrencia

​
Resultados Sinteticos

Quando uma tool_use não 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 não repetir a tool call falha, evitando loops infinitos de retentativa.

​
Validação em 3 Fases

1

Coleta de IDs

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

Detecção 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 Histórico

Reconstroi o histórico: remove orphans, faz dedup de tool_use IDs e injeta resultados sinteticos após 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 três niveis:
NivelLimiteVariável / OverrideDefault
Per-tool (novo)Cap aplicado dentro do dispatch antes da agregaçãoCapability TruncationAware.MaxResultChars() por plugin30.000 chars (global)
Por resultadoTamanho máximo 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

​
Per-tool truncation (capability)

Plugins que implementam plugins.TruncationAware declaram seu próprio cap — útil quando o tool tem necessidade de contexto fora do padrão:
PluginCapJustificativa
@read80 000Arquivos grandes (~1500 linhas) são primary code-learning surface; cap baixo cega o modelo
@search60 000Output estruturado breadth-oriented (file:line:match) — modelo precisa de amplitude
@tree50 000Listagens de monorepo facilmente passam de 30k
Demais plugins30 000Default global
A truncação preserva o shape historic head/tail (preview 5000 chars + suffix 1000 chars + marker [TRUNCATED N chars omitted, M kept]).

​
Como Funciona o Enforcement

O orcamento e aplicado em duas passadas:
Cada resultado individual e verificado contra DefaultPerResultMaxChars (20KB). Se exceder, o conteúdo 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]

​
Persistência em Disco

Resultados truncados são salvos em arquivos temporários dentro do Workspace de Sessão, em vez do antigo diretório global /tmp/chatcli-tool-results/: 
$TMPDIR/chatcli-agent-<random>/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
  result_read_3.txt      # Storage secundário (workers package)
A mudança para o diretório por sessão tem dois efeitos importantes:
  1. Isolamento entre sessões. Múltiplas instâncias de chatcli rodando em paralelo no mesmo host não compartilham mais o pool de overflow.
  2. Leitura sob demanda pelo agente. O scratch dir está na allowlist de leitura do agente, então quando o modelo encontra a marca [full output saved to ...] no preview, ele consegue abrir o arquivo com read_file:
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"/tmp/chatcli-agent-Xy7K3a/tool-results/budget_tc_3_1.txt","start":1200,"end":1500}}' />
Antes desta versão, o caminho era um beco sem saída — o read tool bloqueava por estar fora do workspace boundary. O orçamento “salvava o output” mas o agente não tinha como acessá-lo.
Os arquivos são limpos automaticamente quando a sessão termina (ChatCLI.cleanup), respeitando CHATCLI_AGENT_KEEP_TMPDIR=true para depuração. Não é mais necessária uma limpeza global periódica.

​
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)
ReferênciaCaminho 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 informação crítica:
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]

​
Detecção de Tipo de Conteúdo

O resumo identifica automaticamente o tipo do conteúdo para contexto:
ConteúdoTipo 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

​
Configuração da Microcompactacao

VariávelDescricaoDefault
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 execução sao preservados por conterem informações críticas 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. Histórico limpo enviado para a API

​
Configuração Completa

Variável de AmbienteDescricaoDefault
CHATCLI_TOOL_RESULT_BUDGET_CHARSOrcamento agregado por turno200.000
CHATCLI_TOOL_RESULT_MAX_CHARSTamanho máximo por resultado20.000
CHATCLI_MICROCOMPACT_TRUNCATE_TURNSTurnos para iniciar truncamento2
CHATCLI_MICROCOMPACT_SUMMARIZE_TURNSTurnos para iniciar sumarizacao4

​
Próximos Passos

Workspace de Sessão

Onde os arquivos de overflow vivem e como o agente os lê.

Subagent Delegation

Estratégia complementar para evitar saturar o contexto com dados brutos.

Recuperação de Contexto

O que acontece quando mesmo com orçamento o contexto transborda.

Cost Tracking

Monitore o consumo de tokens incluindo tool results.