Claude Code 2.1.310: correções de gateway e hooks no Windows

Se o Claude Code falha ao acessar um gateway com Unexpected value(s) mencionando effort-2025-11-24, ou com Unexpected role "system", atualize para 2.1.310 ou posterior e tente novamente na conversa afetada. Equipes que usam Windows também devem verificar se uma falha no interpretador de um hook realmente bloqueia a chamada da ferramenta. Se imagens coladas desapareceram enquanto cleanupPeriodDays estava configurado com um valor extremo, preserve os dados restantes antes de alterar a retenção.

Em 2026-10-25, as notas oficiais da versão 2.1.310 confirmam correções para esses casos de gateway, hooks do Windows e limpeza. Os procedimentos abaixo tratam cada falha separadamente.

Confirme que o executável ativo é a versão 2.1.310 ou posterior

Verifique qual executável seu terminal inicia e atualize pelo método de instalação que você já utiliza. No Bash, ou sem alterações no Windows PowerShell, execute:

claude --version
claude doctor

claude doctor fornece diagnósticos de instalação e configuração sem modificá-las. Guarde a saída da versão para compará-la após a atualização.

Use o comando correspondente nas instruções de instalação e atualização da Anthropic:

Instalação existente	Shell	Comando de atualização
Instalador nativo	Bash ou PowerShell	`claude update`
Cask stable do Homebrew	Bash	`brew upgrade claude-code`
Cask latest do Homebrew	Bash	`brew upgrade claude-code@latest`
WinGet	PowerShell	`winget upgrade Anthropic.ClaudeCode`
npm	Bash ou PowerShell	`npm install -g @anthropic-ai/claude-code@latest`

As atualizações nativas seguem o canal de versões configurado. O cask claude-code do Homebrew acompanha stable, enquanto claude-code@latest acompanha latest; portanto, uma atualização pode terminar com sucesso e ainda deixar o cliente abaixo da versão necessária.

Em uma instalação nativa existente, a CLI também permite instalar uma versão específica com claude install 2.1.310. Em uma implantação gerenciada por pacotes, selecione um pacote ou canal que forneça a versão necessária, seguindo o processo habitual dessa implantação.

Execute claude --version novamente e inicie uma nova sessão do Claude Code. Se a versão continuar antiga, procure instalações conflitantes com which -a claude no Bash ou where.exe claude no PowerShell. Se estiver usando o terminal de um editor, talvez seja necessário reiniciar o próprio editor para que ele reconheça a alteração no PATH.

Identifique o erro do gateway e o ajuste automático correspondente

Escolha a correção pelo texto do erro recebido. Um 400 genérico não identifica qual recurso o gateway rejeitou.

O guia de compatibilidade com gateways da Anthropic documenta estas formas de recuperação:

Resposta recebida	Ajuste automático	O que verificar
`400` começando com `Unexpected value(s)` e mencionando `effort-2025-11-24` para `anthropic-beta`	Omite o campo effort e o beta para esse modelo até que o Claude Code seja encerrado.	Remova esse valor se você o adicionou manualmente a `ANTHROPIC_BETAS`.
`400` mencionando `output_config.effort` com `Extra inputs are not permitted`, ou informando que effort não é compatível	Aplica o ajuste alternativo de effort.	Confirme que effort é o campo rejeitado.
`400`, por exemplo `Unexpected role "system"`	Move o texto de sistema inserido no meio da conversa para mensagens de usuário; mantém esse formato até `/clear` ou a compactação do contexto.	Tente novamente na conversa afetada.

O ajuste modifica a requisição. O parâmetro effort controla como o modelo gasta tokens, portanto uma nova tentativa bem-sucedida sem ele não comprova que o nível de effort solicitado foi respeitado. Da mesma forma, mover o texto de sistema para mensagens de usuário preserva o conteúdo, mas altera sua representação.

Reproduza o erro na mesma conversa

Mantenha o mesmo gateway, a mesma origem das credenciais e o mesmo modelo selecionado ao verificar a atualização. Assim, a comparação ajuda a identificar a causa: trocar de provedor e de versão ao mesmo tempo deixaria essa causa incerta.

Primeiro, inicie o Claude Code e execute /status. As instruções de conexão com gateways explicam como confirmar ali a URL base ativa e a origem das credenciais. Se o gateway esperado não aparecer, corrija essa configuração antes de investigar a compatibilidade dele com o beta.

Depois, saia e reabra a conversa afetada, registrando os diagnósticos em um arquivo local. No Bash:

claude --resume --debug-file ./claude-gateway-debug.log

Selecione a sessão que falhou e repita a menor requisição capaz de reproduzir o problema. Essas opções estão documentadas na referência da CLI.

A verificação imediata de sucesso é receber uma resposta útil do assistente onde a requisição anterior falhou. Para comprovar que o ajuste de compatibilidade permitiu a recuperação, examine os diagnósticos disponíveis do cliente e, quando houver, os diagnósticos de requisições do gateway, procurando a rejeição seguida de uma nova tentativa ajustada. Uma primeira mensagem bem-sucedida em uma conversa nova não testa todos os formatos que a conversa pode assumir depois.

No caso do BetterToken, sua configuração para Claude Code especifica ANTHROPIC_BASE_URL=https://bettertoken.ai sem /v1; mantenha esse endereço documentado ao verificar a atualização do cliente.

Se o cliente atualizado continuar falhando

Preserve os corpos das respostas de erro do serviço de origem: substituir uma rejeição reconhecível por um erro genérico do gateway pode impedir a detecção do ajuste necessário. Além disso, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 mantém effort e as mensagens de sistema no meio da conversa, portanto não é uma solução universal para essas falhas.

Escolha a próxima ação de acordo com a evidência restante:

A mesma rejeição reconhecida se repete: confira o executável ativo, os valores beta fornecidos manualmente e se o gateway reescreve o erro do serviço de origem.
A autenticação falha: siga as instruções de credenciais do gateway. O guia de conexão distingue ANTHROPIC_AUTH_TOKEN, usado para autenticação Bearer, de ANTHROPIC_API_KEY, usado para x-api-key; utilize o esquema documentado pelo seu provedor.
O erro menciona outro campo: investigue os requisitos de compatibilidade desse campo. Não classifique toda rejeição de esquema como o problema de effort.
A conexão falha antes de chegar uma resposta da API: investigue o endpoint, o proxy, o DNS ou o caminho TLS.

Se precisar encaminhar o caso ao suporte, reúna a versão do cliente, o sistema operacional, o ID do modelo selecionado, o horário ou ID da requisição, o status HTTP e o erro exato. Compartilhe um trecho dos diagnósticos com os dados sensíveis removidos, em vez de credenciais ou do registro completo da conversa.

Comprove que os hooks do Windows bloqueiam a ação

Atualize para 2.1.310 ou posterior e teste o comportamento em caso de falha de cada hook usado para aplicar políticas. As duas versões consecutivas corrigem situações diferentes:

A 2.1.309 corrige o tratamento dos códigos de saída dos hooks do PowerShell e as falhas por ausência do Git quando os hooks selecionam explicitamente o PowerShell.
A 2.1.310 corrige o caso adicional de ausência do Git Bash em que o comando do hook contém apenas strings entre aspas.

Um erro no hook não resulta automaticamente em uma recusa. A referência de hooks oferece onFailure: "block" para hooks de comando e HTTP que precisam interromper a ação que os acionou quando falham.

Teste a regressão do comando entre aspas

Use um ambiente de teste descartável com Windows nativo, sem Git Bash, com uma conexão funcional do Claude Code e sem outros hooks ou plugins que possam interferir no resultado. Isso verifica o comportamento na ausência do Git Bash sem remover o Git da sua máquina de trabalho.

No PowerShell, crie um diretório de teste novo e um arquivo inofensivo:

$hookProbe = Join-Path $env:TEMP ("claude-hook-probe-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path (Join-Path $hookProbe '.claude') -Force | Out-Null
Set-Location $hookProbe
Set-Content -LiteralPath .\probe.txt -Value ([guid]::NewGuid().ToString())
Test-Path 'C:\__claude_hook_probe_missing__\python.exe'
claude --version

Test-Path deve retornar False, e a versão deve ser pelo menos 2.1.310.

Nesse diretório de teste, crie .claude/settings.local.json com:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "\"C:\\__claude_hook_probe_missing__\\python.exe\""
          }
        ]
      }
    ]
  }
}

A ausência dos campos shell, args e onFailure é intencional: esta etapa examina o próprio comportamento alternativo para comandos entre aspas.

Inicie a sessão no PowerShell:

claude --tools Read --debug-file .\phase1.log

Aceite a confirmação de confiança no espaço de trabalho para esse diretório descartável. Em seguida, execute /hooks e confirme que o hook PreToolUse corresponde a Read. Peça:

Use a ferramenta Read exatamente uma vez para ler probe.txt. Se a chamada for bloqueada, informe isso e pare. Não use outro método.

Resultado esperado: a chamada a Read é bloqueada, com PowerShell started no program no erro ou nos diagnósticos. O PowerShell normalmente avalia um caminho entre aspas como uma string; a documentação da Microsoft sobre o operador de chamada explica por que executar esse caminho exige outra sintaxe.

Se Read conseguir ler o arquivo, o teste falhou. Se o Claude nem sequer tentar executar Read, o resultado é inconclusivo. Examine o resultado da ferramenta e o registro de diagnóstico, em vez de aceitar a descrição do modelo como prova.

Se /hooks não listar a configuração, siga as verificações de carregamento dos hooks. As configurações normalmente são recarregadas automaticamente, mas reiniciar força a recarga caso o monitor de arquivos não tenha detectado a alteração. Uma política que permite apenas hooks gerenciados também significa que esse teste no nível do projeto não foi executado.

Teste um interpretador realmente ausente

Use uma política explícita para falhas e verifique o que acontece quando o interpretador não consegue iniciar. Saia da sessão de teste e substitua apenas o objeto interno do hook por:

{
  "type": "command",
  "command": "C:\\__claude_hook_probe_missing__\\python.exe",
  "args": [],
  "onFailure": "block"
}

Aqui, args seleciona a chamada direta do executável. Agora, a ausência do executável causa uma falha real de inicialização, em vez de produzir uma expressão de string entre aspas.

Reinicie no PowerShell e repita o mesmo pedido para Read:

claude --tools Read --debug-file .\phase2.log

Resultado esperado: Read é bloqueado porque o interpretador não conseguiu iniciar. Essa etapa verifica o tratamento explícito de falhas independentemente da disponibilidade do Git Bash; é uma verificação diferente da regressão do comando entre aspas.

Depois de examinar os resultados, remova a configuração de teste. Nos hooks usados para aplicar políticas reais, restaure o interpretador funcional e mantenha uma política explícita de bloqueio quando uma falha na verificação precisar interromper a ação.

Esses testes exercitam PreToolUse. Um hook PermissionRequest exige uma verificação separada com uma ação que alcance a etapa de permissão. Sua recusa normal usa hookSpecificOutput.decision.behavior definido como "deny"; o código de saída 2, sozinho, não nega esse evento. Uma falha real com onFailure: "block" nega a solicitação.

Substitua valores extremos por um prazo de retenção definido

Use o padrão documentado de 30 dias, a menos que sua equipe tenha um requisito específico de retenção, e arquive o histórico que deseja manter antes de reduzir um prazo existente.

A correção de limpeza trata da exclusão de arquivos recentes associada a valores extremamente altos de cleanupPeriodDays. Ela não transforma essa configuração em um sistema de arquivamento nem restaura arquivos já removidos.

Preserve os dados restantes antes de alterar o prazo

Encerre as sessões ativas e copie os dados que ainda precisa manter para um local fora dos diretórios gerenciados pelo Claude Code. Inclua os dados relevantes de ~/.claude, ou de %USERPROFILE%\.claude no Windows, junto com os anexos de imagem restantes.

A documentação atual dos dados do aplicativo informa que as novas imagens coladas ficam em diretórios images/ de cada sessão, dentro da raiz temporária do Claude Code, controlada por CLAUDE_CODE_TMPDIR. Portanto, fazer backup apenas de ~/.claude não comprova que as cópias atuais das imagens foram preservadas.

Depois de preservar os dados, acrescente esta configuração ao arquivo de configurações apropriado:

{
  "cleanupPeriodDays": 30
}

Para definir um padrão pessoal, esse arquivo é ~/.claude/settings.json, ou %USERPROFILE%\.claude\settings.json no Windows. Preserve as outras chaves existentes.

Conforme a documentação consultada em 2026-10-25, o mínimo é 1; 0 não passa na validação. Reduzir o prazo torna dados mais antigos elegíveis para limpeza, por isso a preservação vem primeiro.

Execute claude doctor para verificar a validade das configurações. Se o valor desejado não estiver sendo aplicado, examine a ordem de precedência das configurações: configurações gerenciadas e configurações de sessão ou projeto com prioridade maior podem substituir as do seu arquivo pessoal. /status mostra as fontes carregadas, mas não o valor efetivo de cada chave individual.

Recupere os anexos ausentes separadamente

Restaure uma imagem ausente a partir do arquivo original ou de um backup existente do sistema de arquivos. Depois, anexe a cópia recuperada à conversa. Verifique se o arquivo abre localmente e se o Claude consegue usar o anexo novamente.

Alterar a retenção não reconstrói bytes apagados. Também não presuma que /rewind recuperará um anexo: os snapshots de checkpoint também expiram, e a restauração pode falhar quando os snapshots necessários já não existem.

Para equipes que já exportam telemetria, examine um evento claude_code.retention_sweep concluído. A referência de monitoramento documenta result: "complete" e period_days com valor do tipo string; "30" confirma que aquela execução específica da limpeza usou 30 dias.

Um reinício breve não basta para comprovar que a limpeza foi executada. Ela ocorre em segundo plano, no máximo uma vez por sessão. Se houve uma execução nas 24 horas anteriores, a limpeza da próxima sessão é adiada por pelo menos 10 minutos. Trate a possibilidade de abrir os anexos e a evidência de uma limpeza concluída como observações separadas.

A disponibilidade do Monitor mudou separadamente

A versão 2.1.310 também disponibiliza a ferramenta Monitor e os monitores de plugins no Bedrock, Vertex e Foundry, inclusive em configurações com telemetria ou tráfego não essencial desativados. As notas da versão também informam que esperas prolongadas em primeiro plano passam a ser bloqueadas nesses ambientes.

Se o Monitor não aparecia em uma dessas implantações, verifique a versão em execução antes de alterar a política de telemetria. Essa mudança de disponibilidade é independente de um gateway específico aceitar configurações de effort ou mensagens de sistema no meio da conversa.