O problema
Uma sessão de duas horas atrás investigou um bug e concluiu, errado, que a causa era no módulo de autenticação. Na manhã seguinte, alguém retoma essa sessão com --resume pra continuar o trabalho — e o agente carrega toda aquela conclusão errada como se ainda fosse verdade, porque nada nela foi marcado como obsoleto. O trabalho da manhã inteira é gasto desfazendo uma premissa que já devia ter sido descartada.
Retomar uma sessão não é neutro. Ela traz de volta tudo que estava lá, inclusive as observações de ferramentas que já perderam validade e as conclusões que já foram refutadas. A decisão de arquitetura aqui é: quando o histórico de uma sessão ainda serve, e quando ele é peso morto que precisa ser substituído por um resumo estruturado explícito.
O conceito central
--resume <nome-da-sessão> continua uma sessão anterior com todo o seu histórico intacto. Isso é exatamente o que você quer quando o contexto acumulado ainda é válido — a sessão foi pausada, não invalidada, e retomar economiza o trabalho de reconstruir tudo que já foi estabelecido. Mas quando alguma observação de ferramenta ficou stale — um arquivo mudou, uma hipótese foi refutada, uma decisão foi revertida — carregar aquele histórico de volta reintroduz o erro. Nesses casos, a escolha certa é começar uma sessão nova com um resumo estruturado explícito: um registro compacto do que é fato confirmado, o que foi descartado e por quê, e o que ainda está em aberto. Isso é mais barato em tokens do que o histórico completo e, mais importante, não carrega premissas obsoletas junto.
fork_session resolve um problema diferente: explorar alternativas sem contaminar a linha principal de raciocínio. Se duas abordagens concorrentes precisam ser testadas — otimizar a query atual vs. reescrever a camada de acesso a dados — bifurcar a sessão permite que cada exploração aconteça isoladamente, sem que o raciocínio de uma vaze pra outra antes de qualquer uma ter se provado certa. Sem bifurcação, a sessão principal fica poluída com becos sem saída de ambas as abordagens, mesmo depois que uma delas é descartada.
A terceira peça é como erros e resultados parciais atravessam a fronteira entre sessões (ou entre sessão principal e subagente). Um subagente que falha no meio de uma tarefa não deve simplesmente desaparecer sem deixar rastro — ele precisa devolver um erro estruturado (o que foi tentado, onde falhou, o que já foi confirmado até aquele ponto) pra que quem retoma o trabalho não repita o mesmo caminho às cegas. Um resultado parcial vale mais que silêncio: "consegui confirmar X e Y, mas não cheguei em Z porque a ferramenta W retornou um erro" é informação acionável. Um subagente que só retorna sucesso ou falha binária, sem esse detalhe, força quem recebe o resultado a refazer a investigação do zero.
O padrão a evitar é tratar --resume como padrão universal só porque é mais conveniente que escrever um resumo. Conveniência não é o critério — validade do contexto é. Uma sessão de duas semanas atrás quase sempre tem mais peso morto que sinal útil; um resumo estruturado de trinta linhas escrito à mão geralmente serve melhor do que retomar automaticamente.
Coloque em prática
No laboratório desta lição você vai implementar uma função que decide entre retomar uma sessão existente ou começar uma nova com resumo estruturado, com base na idade da sessão e em quais fatos dela já foram invalidados — e uma estrutura de erro que propaga resultados parciais de um subagente que não terminou a tarefa.