Claude Code 2.1.251 adiciona hooks para controlar mudanças de modelo antes e depois de ocorrerem, e isso torna a mudança de modelo uma decisão auditável do workflow.
A frase curta do changelog oficial, publicado em 28 de agosto de 2026, é: “Added PreModelSwitch and PostModelSwitch hook events”.
Mas a leitura útil para equipes não é “Claude Code somou dois hooks a mais”. A leitura útil é que o modelo deixou de ser apenas uma preferência individual do desenvolvedor. Em uma sessão longa, com prompt cache, subagentes, permissões, Remote Control, SDKs e possíveis gateways de modelos, mudar de modelo pode ter impacto em custo, política, rendimento, rastreabilidade e dados enviados ao provedor correto.
Aí é onde PreModelSwitch e PostModelSwitch importam.
O primeiro permite intervir antes de que Claude Code aplique uma mudança de modelo solicitada por uma pessoa ou por um cliente. Pode bloquear a mudança, pedir confirmação ou mostrar informação de custo antes de prosseguir. O segundo roda após a sessão já ter mudado de modelo e serve para auditar, registrar ou injetar orientação específica para o modelo novo.
Para equipes que já usam Claude Code seriamente, isso não é cosmética. É governança.
E para equipes na Iberoamérica, onde muitas organizações combinam contas cloud, restrições de segurança, orçamentos por projeto e ferramentas de desenvolvimento heterogêneas, essa governança começa a ser uma vantagem operativa concreta.
Como controlar mudanças de modelo em Claude Code?
Para controlar mudanças de modelo em Claude Code, você usa PreModelSwitch como ponto de decisão antes da mudança e PostModelSwitch como ponto de auditoria ou adaptação depois da mudança.
A documentação oficial posiciona PreModelSwitch antes de que Claude Code aplique uma mudança de modelo solicitada. Esse evento pode bloquear a mudança. Também pode devolver uma decisão de permissões equivalente a permitir, negar ou perguntar ao usuário.
PostModelSwitch, por sua vez, roda após a sessão já ter mudado. Não pode impedir nada porque a mudança já ocorreu, mas sim pode agregar contexto para a próxima solicitação, registrar evidência ou aplicar instruções específicas para o modelo atual.
A diferença parece pequena, mas define duas responsabilidades distintas:
PreModelSwitché política preventiva.PostModelSwitché observabilidade e adaptação.
Se uma equipe quer impedir que certos projetos usem um modelo descontinuado, caro ou não aprovado, o controle pertence a PreModelSwitch. Se quer registrar que uma sessão passou de um modelo econômico para um mais poderoso, ou dar instruções operativas ao modelo novo, o lugar natural é PostModelSwitch.
Esse padrão se parece muito com o que já está ocorrendo com ferramentas, comandos e MCP: os agentes precisam de pontos de intervenção ao redor de suas ações, não apenas prompts gerais no início da sessão.
O que é Claude Code e por que essa mudança importa?
Claude Code é o agente de desenvolvimento da Anthropic para trabalhar sobre repositórios, executar ferramentas e sustentar sessões de programação desde CLI, IDEs, SDKs e fluxos remotos.
Em yoDEV já estamos acompanhando esse movimento em várias camadas: sessões que se comunicam entre máquinas com ListAgents e SendMessage, runners self-hosted para rodar sessões na sua infraestrutura, plugins locais, workflows dinâmicos e SDKs para construir copilotos próprios.
Esse contexto importa porque PreModelSwitch não chega a um produto simples. Chega a uma superfície onde o agente pode trabalhar durante muito tempo, mover contexto entre ferramentas, delegar a subagentes, receber instruções de clientes externos e operar sobre repositórios reais.
Quando o agente trabalha cinco minutos em uma tarefa trivial, mudar de modelo pode parecer uma comodidade. Quando trabalha dentro de um fluxo de equipe, a mudança de modelo toca perguntas mais sérias:
- Esse modelo está aprovado para esse repositório?
- A mudança quebra uma política de custo?
- Se perde um cache quente que já tinha contexto carregado?
- O novo modelo precisa de instruções distintas?
- Quem pediu a mudança: a pessoa, o picker,
/config, fast mode, o SDK ou Remote Control? - A transição ficou registrada para auditoria?
Claude Code 2.1.251 coloca essas perguntas dentro do ciclo de hooks.
Por que mudar de modelo pode custar mais do que parece?
Mudar de modelo pode custar mais do que parece porque uma sessão longa pode ter muito contexto e um prompt cache quente que se perde ao mudar de destino.
A documentação de PreModelSwitch expõe campos projetados justamente para que o hook possa mostrar o custo antes de que a mudança ocorra. Entre eles aparecem context_tokens, prompt_cache_warm, cache_ttl, estimated_cache_write_usd e pricing.
Essa lista conta uma história clara.
Claude Code não apenas informa “você vai de um modelo para outro”. Também dá ao hook dados sobre quantos tokens poderiam ser reenviados, se o cache atual provavelmente ainda está quente, quanto tempo de vida esse cache tem e como se estimou o custo em dólares de escrever esse contexto no cache do modelo de destino.
A documentação esclarece que esse custo é uma estimativa, porque o servidor talvez não precise cachear novamente todo o contexto. Ainda assim, para uma equipe é um sinal suficiente para tomar melhores decisões.
Um caso típico: uma sessão leva horas de conversa, leitura de arquivos e resultados de ferramentas. Alguém muda de um modelo mais econômico para um mais poderoso logo antes de uma pergunta pequena. Sem controle, essa transição pode reemitir uma massa de contexto que não era necessária para a tarefa. Com PreModelSwitch, a equipe pode pedir confirmação quando o custo estimado cruza um limite, bloquear mudanças desde superfícies não interativas ou simplesmente mostrar um aviso.
Isso converte o custo em parte do design do workflow.
Não se trata de repreender o desenvolvedor por escolher um modelo poderoso. Se trata de distinguir quando o modelo poderoso traz valor e quando a mudança ocorre por inércia, hábito ou uma automação demasiado generosa.
Que políticas de modelos pode aplicar uma equipe?
Uma equipe pode usar hooks de mudança de modelo para aplicar listas de modelos aprovados, descontinuar modelos obsoletos, pedir confirmação ante custos altos e registrar mudanças feitas desde SDKs ou Remote Control.
A documentação oficial mostra que PreModelSwitch se dispara para mudanças pedidas desde /model, desde o picker de modelos, desde a configuração, ao ativar fast mode quando isso muda o modelo, ou desde solicitações set_model e mudanças de modelo enviadas por hosts do Agent SDK ou Remote Control.
Esse leque é importante. Se o controle apenas cobrisse a UI interativa, seria uma comodidade local. Ao cobrir SDK e Remote Control, se torna uma peça para ambientes onde Claude Code está integrado em fluxos mais amplos.
Algumas políticas razoáveis:
- Bloquear modelos descontinuados ou não aprovados pela equipe.
- Pedir confirmação quando
estimated_cache_write_usdsupere um limite. - Permitir mudanças para modelos baratos sem atrito e pedir aprovação para modelos premium.
- Negar mudanças de modelo desde automatizações não interativas.
- Registrar
from_model,to_model,sourceepricingem um sistema interno. - Mostrar um aviso quando
prompt_cache_warmseja verdadeiro e a mudança implique perder essa vantagem.
A parte fina está em não codificar políticas demasiado frágeis.
Claude Code compara matchers contra nomes canônicos de modelos. A documentação também avisa que, se não conseguir determinar um nome canônico para o destino, por exemplo atrás de um gateway que usa IDs próprios, roda todos os hooks de PreModelSwitch sem depender do matcher. Por isso uma política robusta deveria revisar o campo to_model recebido pelo hook, não confiar apenas no matcher.Esse detalhe é exatamente o tipo de borda que torna esses hooks relevantes para equipes, não apenas para usuários avançados.
Qual é a diferença entre bloquear, perguntar e anotar?
Bloquear, perguntar e anotar são três níveis distintos de controle operacional sobre a mudança de modelo.
Bloquear é a decisão forte. No Claude Code, um hook pode cancelar a mudança com uma decisão de bloqueio ou com o código de saída documentado para ações bloqueantes. É a opção correta quando o modelo não está aprovado, a rota viola uma política ou a automação tenta uma mudança que a equipe não quer permitir.
Perguntar é útil quando a mudança pode ser razoável, mas merece uma confirmação humana. Por exemplo, subir para um modelo mais caro com 180.000 tokens de contexto pode estar bem se a sessão está resolvendo uma migração complexa. Também pode ser desnecessário se a pessoa apenas quer uma resposta curta. A confirmação devolve contexto ao humano antes de gastar.
Anotar é o modo menos intrusivo. Um hook pode mostrar ou adicionar informações sem impedir a transição. Aqui entram avisos de custo, notas de auditoria ou instruções posteriores para o modelo novo.
O matiz operacional: ask só faz sentido onde Claude Code pode mostrar uma confirmação interativa. A documentação indica que, em superfícies não interativas como -p, /config ou requisições set_model, essa decisão é tratada como uma negação. Para fluxos automatizados, é conveniente desenhar políticas explícitas: permitir ou negar, não depender de uma pergunta que ninguém verá.
Por que PostModelSwitch também importa se não pode bloquear?
PostModelSwitch importa porque muitas mudanças de modelo não são solicitadas pela pessoa e mesmo assim deveriam ficar visíveis para a equipe.
A documentação diz que PostModelSwitch roda após mudanças solicitadas, mudanças automáticas como fallbacks, entradas ou saídas de certos modos e restaurações de modelo ao retomar uma sessão. Também esclarece que não roda quando uma cadeia de fallback substitui o modelo apenas por um turno sem mudar o modelo da sessão.
Esse comportamento o torna útil para auditoria.
Se uma sessão mudou de modelo por fallback automático, a equipe talvez não pudesse bloqueá-lo com PreModelSwitch, porque não foi uma mudança pedida pelo usuário ou cliente. Mas sim pode registrá-lo depois. Em ambientes com compliance, faturamento interno ou análise de qualidade, essa diferença entre “modelo solicitado” e “modelo efetivamente usado pela sessão” não é menor.
Também serve para instruções operacionais. Uma equipe pode querer que certos modelos recebam contexto adicional: delegar implementação a subagentos, limitar-se a planejamento, evitar chamadas a ferramentas caras ou deixar uma nota de revisão mais rigorosa. PostModelSwitch pode adicionar esse contexto ao próximo request após a mudança.
Não substitui CLAUDE.md nem regras de projeto. Funciona como uma camada dinâmica que depende do modelo ativo.
O que isso tem a ver com permissões e segurança?
Tem a ver com permissões e segurança porque a mesma versão que adiciona hooks de mudança de modelo também corrige várias bordas de permissões, rotas e settings.
Claude Code 2.1.251 não chegou apenas com PreModelSwitch e PostModelSwitch. O changelog também menciona correções para casos onde ferramentas de arquivo podiam seguir um symlink alterado dentro do diretório de trabalho após a verificação de permissões, comandos de plugins podiam apontar para fora do diretório do plugin, workflows podiam ler rotas antes da verificação de permissões, e Grep/Glob não aplicavam certas regras de negação sobre rotas alcançadas por symlinks.
Também aparecem ajustes em torno de rastreamento, logging bruto de corpos de API e comportamentos de settings sob escopos mais altos.
O sinal de fundo é claro: Claude Code está se movendo em uma zona onde as bordas importam. Não basta que o agente seja capaz. Tem que ser operável sob restrições.
Isso se encaixa com uma conversa mais ampla que também vimos em outras ferramentas: os agentes de código precisam de sandboxing, não apenas de bons prompts, e a aprovação de comandos deveria modelar capacidades, não fazer correspondência superficial.
Os hooks de modelo são outra parte da mesma arquitetura.
O modelo decide como o agente raciocina. As ferramentas decidem o que ele pode tocar. As permissões decidem o que ele pode executar. O cache e o gateway decidem quanto custa e por onde viaja o contexto. Se qualquer uma dessas camadas mudar sem visibilidade, a equipe perde controle.
Como uma equipe deveria começar com esses hooks?
Uma equipe deveria começar com uma política pequena: registrar todas as mudanças de modelo, pedir confirmação quando o contexto for grande e bloquear apenas os modelos explicitamente não aprovados.
Essa abordagem evita dois extremos ruins. Por um lado, deixar cada sessão mudar de modelo sem rastreabilidade. Por outro, criar uma política tão rígida que os desenvolvedores desativem os controles para poder trabalhar.
Uma primeira iteração prática poderia separar três objetivos:
- Visibilidade: registrar
from_model,to_model,source,context_tokens,prompt_cache_warm,estimated_cache_write_usdepricing. - Custo: pedir confirmação quando o custo estimado de re-cachear contexto for alto ou quando o cache estiver quente.
- Política: bloquear modelos descontinuados, não aprovados ou incompatíveis com um repositório específico.
Depois de uma semana de uso real, a equipe pode olhar para evidência em vez de discutir preferências:
- Quais modelos são realmente usados.
- De quais superfícies os pedidos de mudança vêm.
- Quantas mudanças ocorrem com cache quente.
- Quantas confirmações foram úteis.
- Quais automações tentam mudar de modelo.
- Quais repositórios precisam de regras distintas.
A governança boa não começa com uma matriz perfeita. Começa tornando visível o comportamento real.
Qual é o aviso com Claude Code 2.1.251?
O aviso é que esses detalhes têm alto risco de degradação: nomes de modelos, campos de linha de status, semântica de hooks, gateways e rotas de configuração podem mudar rapidamente.
No momento de publicar essa nota, 1 de setembro de 2026, a documentação oficial marca PreModelSwitch e PostModelSwitch como disponíveis desde Claude Code v2.1.251. O changelog já mostra uma versão posterior, 2.1.252, publicada em 31 de agosto de 2026, com correções adicionais. Isso não invalida a mudança de 2.1.251, mas confirma que o trem de releases se move rápido.
Por isso é conveniente tratar essa nota como um guia de critério, não como uma receita congelada. Antes de copiar uma política para produção, revise a documentação oficial de hooks e o changelog atual.
A parte duradoura é o padrão.
Os agentes de código não são mais uma caixa de chat que sugere funções. São runtimes que executam ferramentas, consomem contexto, usam cache, delegam trabalho, se conectam por SDK e podem mudar de modelo dentro de uma sessão viva.
Nesse mundo, “que modelo usamos” não é uma preferência estética.
É uma decisão de operação.
E Claude Code 2.1.251 acabou de dar aos equipes um lugar explícito para controlá-la.