Guia do Claude Code CLI: instalação, configuração, comandos e variáveis de ambiente

TL;DR: Claude Code é uma CLI agêntica que lê sua base de código, executa comandos e edita arquivos, controlada por cinco sistemas: configuração, permissões, hooks, MCP e subagents. Use hooks, não prompts, para tudo o que precisa ser executado sempre.

Situação atual (CLI v2.1.292, 6 de outubro de 2026; latest e next do npm estão na versão 2.1.292, enquanto stable está na 2.1.285):²³⁴

• Modelo padrão: Claude Opus 5.5 (claude-opus-5-5) nos planos Pro, Max, Team e Enterprise, na Anthropic API, na Claude Platform no AWS, no Amazon Bedrock e na Agent Platform do Google Cloud. O Microsoft Foundry é a exceção: seu padrão é o Sonnet 4.5, e o alias opus corresponde ao Opus 4.6.²²¹
• Resumo do Opus 5.5: US$ 4/US$ 20 por milhão de tokens, com leituras de cache a US$ 0,20, contexto de 1 milhão por padrão na Anthropic API e, desde a v2.1.287, no Bedrock, na Agent Platform e no Foundry, esforço medium por padrão e raciocínio que não pode ser desativado. O modo rápido o executa por US$ 8/US$ 40. O Sonnet 5.5 (US$ 2/US$ 10; sonnet na Anthropic API desde a v2.1.284) é a opção mais econômica quando uma tarefa não exige o Opus.^{220222223228232}
• O modo Auto é o modo de permissão inicial para sessões interativas no terminal e no VS Code em todos os planos e provedores (v2.1.283-284), enquanto sessões de claude -p e do Agent SDK começam no modo Manual, a menos que --permission-mode auto seja fornecido (a v2.1.302 reverteu o início automático introduzido na v2.1.285 para provedores de terceiros e quando a telemetria está desativada).²⁷⁵ Suas verificações de segurança são executadas no servidor sem custo adicional para contas Enterprise e da Claude API, na Claude Platform no AWS, no Bedrock, na Agent Platform e no Foundry, além de gateways, usando verificações locais cobradas como alternativa.^{219227228229230}
• AGENTS.md: desde a v2.1.277, AGENTS.md é lido como instruções do projeto quando um projeto não possui CLAUDE.md, exceto onde as feature flags não são obtidas (como no Bedrock) e na primeira sessão após uma instalação ou atualização.²¹⁹²²³

O histórico de cada versão está no Changelog.

Claude Code funciona como um sistema agêntico, não como uma interface de chat com conhecimento de programação. A CLI lê sua base de código, executa comandos, modifica arquivos, gerencia fluxos de trabalho do git, conecta-se a serviços externos por meio do MCP e delega tarefas complexas a subagents especializados. Tudo acontece por uma interface de linha de comando integrada à maneira como os desenvolvedores realmente trabalham. Em fevereiro de 2026, 4% dos commits públicos no GitHub (cerca de 135.000 por dia) eram criados pelo Claude Code — um crescimento de 42.896 vezes nos 13 meses desde a versão preliminar de pesquisa — e 90% do código da própria Anthropic era escrito por IA.¹⁰³

A diferença entre o uso casual e o uso eficaz do Claude Code se resume a cinco sistemas essenciais. Domine-os e o Claude Code se tornará um multiplicador de produtividade:

1. Hierarquia de configuração: controla o comportamento
2. Sistema de permissões: controla as operações
3. Sistema de hooks: permite automação determinística
4. Protocolo MCP: amplia as funcionalidades
5. Sistema de subagents: processa tarefas complexas com várias etapas

Principais conclusões

• Cinco sistemas determinam sua eficácia: a hierarquia de configuração, as permissões, os hooks, o MCP e os subagents controlam tudo, desde o comportamento até a automação.
• Transfira o trabalho para a camada de delegação: os subagents evitam o excesso de contexto ao isolar a exploração em janelas de contexto limpas e retornar apenas resumos.
• Hooks garantem a execução; prompts não: use hooks para linting, formatação e verificações de segurança que precisam ser executadas sempre, independentemente do comportamento do modelo.
• A divisão dos modelos em níveis reduz custos sem comprometer a qualidade: direcione a exploração dos subagents para modelos mais baratos e reserve o Opus para tarefas que realmente exijam raciocínio arquitetural — ou padronize o uso do Opus se a qualidade for sua única variável.
• O MCP conecta a Claude ao seu conjunto de ferramentas: bancos de dados, GitHub, Sentry e mais de 3.000 integrações ampliam a Claude para além da leitura de arquivos e dos comandos bash.

Passei meses levando o Claude Code ao limite em bases de código de produção, pipelines de CI/CD e implantações empresariais. Este guia condensa essa experiência na referência completa que eu gostaria que existisse quando comecei. Cada recurso inclui a sintaxe exata, exemplos reais de configuração e os casos extremos que surpreendem até usuários experientes.

Escolha seu caminho

Como usar este guia

Esta é uma referência com mais de 5.000 linhas — você não precisa lê-la do início ao fim. Comece pela seção adequada ao seu nível de experiência:

Use Ctrl+F / Cmd+F no navegador para procurar flags, comandos ou chaves de configuração específicos. O Cartão de referência rápida, no final, apresenta um resumo de fácil consulta com todos os principais comandos.

Análises detalhadas relacionadas

Estes posts exploram em profundidade aspectos específicos do Claude Code:

Início rápido de 60 segundos

Se você só quer executar Claude Code e ver a saída, faça isto na ordem:

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

É isso. Tudo abaixo desta seção detalha as opções de instalação, configura permissões e hooks, conecta servidores MCP e aborda a implantação corporativa — mas nada disso é necessário para começar.

Pré-requisitos: Node 22+ apenas para o caminho npm legado (aumentado de 18 com a v2.1.198; a documentação de instalação atual diz “Node.js 22 or later”, verificado em 07 de agosto de 2026); o instalador nativo recomendado não depende do Node. macOS / Linux / Windows 10+ são compatíveis. Uma assinatura Claude Pro, Max, Team ou Enterprise, ou uma chave Anthropic API paga por token, cobre o uso. Consulte Como instalo o Claude Code? para detalhes específicos da plataforma, solução de problemas e o caminho do binário nativo (padrão desde a v2.1.113). As evidências da versão mais recente neste guia são mantidas a cada lançamento; consulte a linha mais recente do Changelog para ver a marca de verificação atual.²⁶⁷

Como o Claude Code funciona: o modelo mental

Antes de explorar os recursos, entenda como a arquitetura do Claude Code molda tudo o que você faz com ele. O sistema opera em três camadas:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Subagents (20 concurrent default)      │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Camada principal: Sua conversa principal. Cada mensagem, leitura de arquivo e saída de ferramenta consome contexto de uma janela compartilhada (200 mil tokens como padrão⁹¹, 1 milhão de tokens com Opus 4.6 ou modelos de contexto estendido). Quando o contexto se enche, o Claude perde o acompanhamento de decisões anteriores e a qualidade diminui. Essa camada custa dinheiro por token.

Camada de delegação: Subagents são iniciados com contextos limpos, fazem trabalhos focados e retornam resumos. Os resultados da exploração não sobrecarregam sua conversa principal; apenas as conclusões retornam. Direcione subagents para níveis de modelo mais baratos durante a exploração ou use seu modelo principal em todo o processo se a qualidade for mais importante que o custo.

Camada de extensão: O MCP conecta serviços externos (bancos de dados, GitHub, Sentry). Hooks garantem a execução de comandos de shell independentemente do comportamento do modelo. Skills codificam conhecimento especializado que o Claude aplica automaticamente. Plugins empacotam tudo isso para distribuição.

O insight principal: A maioria dos usuários trabalha inteiramente na camada principal, vendo o contexto aumentar e os custos subirem. Usuários avançados levam a exploração e o trabalho especializado para a camada de delegação, mantêm a camada de extensão configurada para seu fluxo de trabalho e usam a camada principal apenas para orquestração e decisões finais.

Sumário

1. Como instalo o Claude Code?
2. Início rápido: sua primeira sessão
3. Modos principais de interação
4. Análise aprofundada do sistema de configuração
5. Qual modelo devo escolher?
6. Quanto custa o Claude Code?
7. Frameworks de decisão
8. Como funciona o sistema de permissões?
9. Como funcionam os hooks?
10. O que é MCP (Model Context Protocol)?
11. O que são subagents?
12. O que é o modo de raciocínio estendido?
13. Estilos de saída
14. Comandos com barra
15. Como funcionam as skills?
16. Sistema de plugins
17. Como funciona a memória?
18. Entrada de imagem e multimodal
19. Modo de voz
20. Como funciona a integração com Git?
21. Como uso o Claude Code no meu IDE?
22. Padrões avançados de uso
23. Agentes remotos e em segundo plano [RESEARCH PREVIEW]
24. Claude no Chrome
25. Claude Code no Slack [RESEARCH PREVIEW]
26. Claude Code na Web [RESEARCH PREVIEW]
27. Claude no Microsoft 365 (maio de 2026)
28. Otimização de desempenho
29. Como depuro problemas?
30. Implantação corporativa
31. Referência de atalhos de teclado
32. Boas práticas
33. Receitas de fluxo de trabalho
34. Guia de migração
35. Orientações específicas por público
36. Cartão de referência rápida
37. Changelog
38. Referências

Como instalar o Claude Code?

Requisitos do sistema

O Claude Code funciona no macOS 13+, Ubuntu 20.04+/Debian 10+ e Windows 10+ (nativo ou WSL). O sistema exige no mínimo 4 GB de RAM e uma conexão ativa com a internet.⁹² A compatibilidade com shells funciona melhor com Bash, Zsh ou Fish.

No Windows, tanto o WSL 1 quanto o WSL 2 funcionam. O Git Bash também funciona se você preferir o Windows nativo. O Alpine Linux e outros sistemas baseados em musl exigem pacotes adicionais:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Matriz de compatibilidade de plataformas

Instalação, atualização e desinstalação em resumo

Consulta rápida — todos os métodos, todos os comandos e a verificação de versão em uma única tela. As subseções abaixo apresentam os detalhes e a solução de problemas de cada método.

Desde a v2.1.113, o CLI canônico inicia um binário nativo do Claude Code por meio de uma dependência opcional específica para cada plataforma, em vez do JavaScript incluído — use o instalador nativo para a distribuição testada. O caminho via npm ainda funciona, mas exibe o aviso de descontinuação adicionado originalmente na v2.1.15.

Métodos de instalação

Instalação nativa (recomendada)

O binário nativo oferece a experiência mais simples, sem depender do Node.js:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Para instalar uma versão específica:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Uma versão que você nunca deve fixar ao usar um proxy ou gateway: 2.1.275. Nessa build, todas as solicitações falham com 400 ... Input tag 'advisor_20260301' quando ANTHROPIC_BASE_URL aponta para um proxy ou gateway; a 2.1.276 corrige a regressão.²¹⁸

Instalação via NPM (descontinuada)

Observação: desde a v2.1.15, as instalações via npm exibem um aviso de descontinuação. O binário nativo agora é o método de instalação recomendado. Migre com claude install.

Para ambientes legados nos quais o npm ainda é necessário:

npm install -g @anthropic-ai/claude-code

Nunca use sudo para instalar via npm. Isso cria problemas de permissão que complicam todas as etapas seguintes.

Migração de uma instalação existente

Se você tiver uma instalação antiga baseada em npm, migre para o binário nativo:

claude install

Opções de autenticação

O Claude Code oferece três formas de autenticação, cada uma com vantagens e desvantagens diferentes:

Console do Claude (cobrança do API)

Conecte-se diretamente ao API da Anthropic por meio de platform.claude.com (anteriormente console.anthropic.com). Crie uma conta, configure a cobrança e faça a autenticação pelo CLI. O Console oferece cobrança baseada no uso, com acesso completo ao API. Um workspace dedicado chamado “Claude Code” é criado automaticamente; você não pode criar chaves do API para esse workspace, mas pode monitorar o uso. Desde a v2.1.243, /login → Console da Anthropic oferece uma opção sem chave, “Entrar com sua conta do Console” (recomendada), além da criação de uma chave do API. Assim, organizações que não permitem chaves do API ainda podem entrar usando as credenciais do Console.²⁵⁰

Assinatura Pro ou Max do Claude

Use as credenciais da sua conta claude.ai. A assinatura cobre tanto a interface web quanto o uso do CLI em um único plano mensal. Ela simplifica a cobrança para usuários individuais que desejam custos previsíveis.

Plataformas empresariais

AWS Bedrock, Google Vertex AI e Microsoft Foundry oferecem acesso de nível empresarial aproveitando as relações de cobrança existentes com os provedores de nuvem. Assistente de configuração do Bedrock (v2.1.92+): um assistente interativo na tela de login orienta você durante a autenticação na AWS, a seleção da região, a verificação das credenciais e a fixação do modelo.¹³⁷ Assistente de configuração do Vertex AI (v2.1.98+): um assistente equivalente para o Google Cloud orienta você durante a autenticação no GCP, a configuração do projeto e da região, a verificação das credenciais e a fixação do modelo.¹⁴² Workload Identity Federation com mTLS no Vertex AI (v2.1.121+): o Vertex AI agora aceita Workload Identity Federation baseada em certificados X.509 (Application Default Credentials com mTLS) — tokens do GCP de curta duração emitidos com base em um certificado de cliente, sem exigir JSON de conta de serviço.¹⁵⁴ Confiança nos certificados de CA do sistema operacional (v2.1.101+): proxies TLS empresariais agora funcionam por padrão — o Claude Code confia no repositório de certificados do sistema operacional. Defina CLAUDE_CODE_CERT_STORE=bundled para usar somente as CAs incluídas.¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

Para implantações empresariais atrás de proxies ou por meio de gateways do LLM:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Cabeçalhos de informações para gateways (v2.1.273): o Claude Code pode adicionar cabeçalhos de solicitação que um gateway do LLM pode usar para roteamento e observabilidade — x-claude-code-request-class, x-claude-code-agent-type, x-claude-code-prev-tool-durations, x-claude-code-compaction, x-claude-code-context-compacted e, desde a v2.1.283, x-claude-code-prompt-id, um UUID aleatório compartilhado por todas as solicitações que atendem a um único prompt do usuário, incluindo turnos de subagents.²¹⁷²²⁶ Com uma URL base personalizada ou um provedor terceirizado, como o Bedrock, os cabeçalhos permanecem desativados até você definir CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. A documentação do protocolo de gateway acrescenta que uma conexão direta ao API da Anthropic os envia por padrão e que CLAUDE_CODE_GATEWAY_HINT_HEADERS=0 interrompe o envio em todas as conexões.²²⁷

Verificação

claude doctor

O comando informa o tipo de instalação, a versão, a configuração do sistema e todos os problemas detectados.

Gerenciamento da autenticação (v2.1.41+)

Gerencie a autenticação sem entrar no REPL:⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

Desde a v2.1.268, claude auth status --json inclui configDirectory — o diretório de configuração que o CLI está realmente lendo, o que é útil quando o redirecionamento por CLAUDE_CONFIG_DIR torna isso ambíguo.²¹⁶

Desde a v2.1.273, entrar com uma conta do Claude também solicita acesso aos seus plugins do claude.ai.²¹⁷

Desde a v2.1.286, claude auth status informa a chave armazenada do API de um login pelo Console como api_key, em vez de claude.ai.²³¹

Fluxo comum para alternar entre contas ou organizações:

claude auth logout && claude auth login

Veja também: Como depurar problemas? para solucionar falhas de autenticação.

Atualizações

O Claude Code é atualizado automaticamente por padrão, verificando atualizações ao iniciar e periodicamente durante as sessões. As atualizações são baixadas em segundo plano e aplicadas na próxima inicialização.

Desative as atualizações automáticas:

export DISABLE_AUTOUPDATER=1

Ou no settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Atualização manual:

claude update

Desinstalação

Instalação nativa (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Instalação nativa (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Limpar a configuração (remove todas as configurações):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Início rápido: sua primeira sessão

1. Instale e inicie:

claude                           # Launch in current directory

2. Acesse um projeto:

cd ~/my-project && claude        # Or launch from any git repo

3. Peça ao Claude para fazer algo:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Use atalhos de teclado durante sua sessão:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Continue mais tarde:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Dica de especialista: Crie um arquivo CLAUDE.md na raiz do seu projeto com comandos de build, convenções de código e observações sobre a arquitetura. O Claude lê esse arquivo em todas as sessões — é a ação de maior impacto que você pode realizar para melhorar a qualidade.

Modos principais de interação

REPL interativo

Inicie Claude Code sem argumentos para entrar no loop interativo de leitura, avaliação e impressão:

cd your-project
claude

O REPL mantém o contexto da conversa entre as interações. Digite as consultas diretamente, receba as respostas e continue até sair com /exit ou Ctrl+D.

Comece com um prompt inicial para direcionar a sessão:

claude "explain the authentication flow in this project"

Dica de especialista: o REPL mantém o estado durante os eventos de compactação. Quando o contexto fica grande demais, Claude resume automaticamente partes mais antigas da conversa, preservando decisões importantes e trechos de código. Você pode acionar isso manualmente com /compact ou adicionar instruções personalizadas sobre o que preservar.

Modo não interativo

O modo de impressão (-p) executa uma única consulta e encerra:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Para obter uma saída estruturada adequada para processamento em scripts:

claude -p "count lines by file type" --output-format json

A saída JSON inclui tudo o que você precisa para automação:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Para processar a saída em streaming em tempo real:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Opções de formato de saída:

Texto de subagents no stream-json (v2.1.211+): por padrão, a saída stream-json contém apenas os eventos da sessão principal — o trabalho realizado nos subagents aparece como um resumo. A flag --forward-subagent-text (ou CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1) também encaminha o texto e a saída de raciocínio dos subagents para o stream, permitindo que harnesses e pipelines de logs observem o trabalho delegado enquanto ele acontece, em vez de ver apenas o relatório final.¹⁸⁸

Subagents aninhados agora também são encaminhados (v2.1.219). Originalmente, apenas os subagents de profundidade 1 apareciam. Agora, os subagents iniciados na profundidade 2 ou superior também aparecem no stream encaminhado, cada um identificado pelo ID tool_use da chamada Agent que o iniciou — assim, um pipeline pode reconstruir a árvore de delegação em vez de ver uma lista simples de textos. Isso complementa diretamente a restauração, na mesma versão, da criação aninhada até a profundidade 3 por padrão: sem esse recurso, 2 dos 3 níveis ficariam invisíveis.¹⁹⁶

Subagents em segundo plano não ficam mais sem resposta (v2.1.273): a saída de SDK e stream-json deixou de descartar as mensagens restantes e o relatório final de um subagent depois que ele é movido para segundo plano durante a execução (por exemplo, por CLAUDE_AUTO_BACKGROUND_TASKS).²¹⁷

Uma execução travada de -p agora retorna um erro (v2.1.277): sessões de claude -p e Agent SDK que encontravam um erro interno podiam ficar travadas sem apresentar resultado — o pior modo de falha para um pipeline, no qual apenas um timeout externo encerrava a execução. Agora, elas informam o erro e encerram com o código 1, fazendo com que a tabela de códigos de saída abaixo volte a representar todo o contrato. A mesma versão também faz com que sessões headless salvem os totais de custo e uso ao encerrar: a retomada de uma sessão headless (claude -p --resume, o SDK, o recarregamento da janela de uma extensão do VS Code) não começa mais com os totais da sessão zerados, evitando que a contabilização de custos fique abaixo do valor real em execuções headless retomadas.²¹⁹

Códigos de saída:

Como controlar o comportamento autônomo no modo -p:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-5

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+); only CLI-named MCP servers (v2.1.286)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

# Restricted mode for eval harnesses and shared machines (v2.1.248+)
claude --restricted -p "query" --tools "Read,Grep,Glob"

# Unattended hosts: deny anything that would prompt (v2.1.259+)
claude -p "run the nightly checks" --permission-prompts none

Modo restrito (v2.1.248+): --restricted (ou CLAUDE_CODE_RESTRICTED=1) foi criado para harnesses de avaliação que executam claude em uma máquina compartilhada. Ele remove as ferramentas integradas que executam comandos ou código e o WebFetch, a menos que você as especifique individualmente em --tools — o preset default não conta —, restringe as ferramentas integradas de arquivos aos diretórios de trabalho, carrega apenas as configurações gerenciadas e --settings (os arquivos de configurações do usuário, do projeto e locais são ignorados), recusa bypassPermissions e não permite criar sessões na nuvem.²⁰⁶²⁰⁹

--permission-prompts none (v2.1.259): o recurso complementar para hosts sem supervisão. Tudo o que geraria uma solicitação de permissão é negado automaticamente, enquanto o modo de permissão ativo — inclusive o modo automático — continua tomando todas as decisões que puder sem você. Não confunda essa opção com --permission-prompt-tool, que delega as solicitações a uma ferramenta MCP em vez de recusá-las. A referência CLI ainda não inclui a nova flag; o CHANGELOG é a fonte.²¹¹

cd persiste entre interações em sessões não interativas (v2.1.265): sessões -p que recebem entrada stream-json, sessões Agent SDK e sessões na nuvem não redefinem mais o diretório de trabalho do shell a cada nova mensagem do usuário — um cd executado em uma interação agora permanece válido na próxima.²¹⁵

--system-prompt-snapshot off (v2.1.267): por padrão, uma conversa reutiliza o system prompt registrado em todas as solicitações. Essa flag faz com que o system prompt seja renderizado novamente a cada solicitação — é a opção ideal para iterar no texto do prompt, quando cada execução precisa incorporar sua edição mais recente em vez do snapshot, ao custo da estabilidade do cache de prompts que o snapshot foi criado para proteger.²¹⁶

--bare mantém suas restrições (v2.1.286): agora, --bare conecta apenas os servidores MCP especificados na linha de comando, não envia lembretes de sistema ao modelo e não inicia tarefas em segundo plano; um comando do shell que atinge o timeout é interrompido em vez de ser movido para segundo plano. A documentação de headless informa que, antes da v2.1.286, essas restrições eram aplicadas apenas parcialmente e recomenda --bare para chamadas em scripts e SDK.²³¹²³³

Padrão de integração com CI/CD:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Gerenciamento de sessões

As sessões preservam o histórico da conversa para que ela possa continuar. A persistência das sessões é essencial para trabalhos complexos que abrangem várias sessões:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

# Open the Claude desktop app on this directory, or on a session (v2.1.285)
claude --desktop
claude --desktop --continue

Mova uma sessão em execução com /cd (v2.1.169+; configuração imediata desde a v2.1.246): /cd path altera o diretório de trabalho sem invalidar o cache de prompts. Desde a v2.1.246, as configurações do projeto no novo diretório, os hooks, os servidores de .mcp.json (sujeitos à solicitação de aprovação habitual), as skills e os agents entram em vigor imediatamente após a mudança, em vez de aguardar --resume.²⁶²²⁴⁹

Sessões vinculadas a PRs (v2.1.27+, ampliadas na v2.1.119+): inicie uma sessão vinculada a uma solicitação de pull ou merge específica. Desde a v2.1.119, --from-pr aceita URLs de MRs do GitLab, PRs do Bitbucket e PRs do GitHub Enterprise, além de github.com:⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

As sessões também são vinculadas automaticamente a PRs quando você as cria com gh pr create durante uma sessão. Isso facilita retomar posteriormente o trabalho em uma PR específica. O selo da PR no rodapé pode apontar para uma URL personalizada de revisão de código por meio da configuração prUrlTemplate (v2.1.119+) — útil quando sua equipe vincula PRs a uma ferramenta de revisão separada.¹⁵²

/resume aceita URLs de PRs (v2.1.122+). Ao colar a URL de uma PR na caixa de pesquisa de /resume, agora é possível encontrar a sessão que criou originalmente essa PR — funciona com github.com, GitHub Enterprise, gitlab.com (inclusive GitLab auto-hospedado) e bitbucket.org.¹⁵⁴

Sessões nomeadas: nomeie as sessões ao iniciá-las ou durante uma sessão:

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Observação: --session-id exige um UUID válido (por exemplo, 550e8400-e29b-41d4-a716-446655440000). Para usar nomes de sessão legíveis, prefira /rename e --resume.

/fork inicia uma sessão em segundo plano; /subtask é a bifurcação dentro da sessão (v2.1.212). Agora, o comando /fork copia a conversa atual para uma nova sessão em segundo plano — ela recebe sua própria linha em claude agents, permitindo que você envie a cópia para explorar uma alternativa enquanto a sessão principal continua. O comportamento anterior — criar uma bifurcação dentro da sessão atual — continua disponível com o novo nome /subtask.¹⁸⁹ Desde a v2.1.214, uma sessão iniciada como bifurcação informa a origem do hook SessionStart como "fork" (antes era "resume"), permitindo que hooks que filtram por origem diferenciem os dois casos.¹⁹⁰ A v2.1.216 simplifica a confirmação de /fork para uma única linha que exibe o nome da nova sessão e seu ID de claude attach.¹⁹² Desde a v2.1.221, uma sessão bifurcada cria seu próprio worktree em vez de trabalhar no checkout da sessão original — assim, a bifurcação que explora uma alternativa não pode mais entrar em conflito com os arquivos não commitados da sessão principal, que era o principal risco ao enviar uma cópia para fazer experimentos.¹⁹⁹ A v2.1.232 também torna a bifurcação o comportamento padrão dos subagents: um subagent com subagent_type: "fork" herda toda a conversa e o cache de prompts, e os agents que não são membros da equipe iniciados em sessões interativas agora são executados em segundo plano por padrão.²⁵⁵

Claude Code armazena as sessões como transcrições JSONL. A execução de agents atribui valores agentId exclusivos, com as transcrições armazenadas como agent-{agentId}.jsonl. A retomada preserva todo o contexto das conversas anteriores.

Modo de planejamento

O modo de planejamento restringe Claude à exploração somente leitura — sem editar arquivos, executar Bash ou realizar ações destrutivas. Claude elabora uma abordagem de implementação, grava-a em um arquivo de plano e aguarda sua aprovação antes de executar qualquer ação.

Como entrar no modo de planejamento:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

Como funciona:

1. Claude entra no modo de planejamento (automaticamente para tarefas complexas ou por meio de Shift+Tab)
2. Explora a base de código usando ferramentas somente leitura: Read, Glob, Grep, WebSearch, WebFetch
3. Grava um plano em .claude/plans/{session-slug}.md
4. Sai do modo de planejamento com ExitPlanMode e apresenta o plano para sua análise
5. Você aprova, solicita alterações ou rejeita

Ferramentas disponíveis no modo de planejamento: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. As ferramentas de edição (Edit, Write, Bash, NotebookEdit) ficam bloqueadas.

Após a aprovação do plano (v2.1.32+): Claude oferece três opções: - “Sim, limpar o contexto e aceitar as edições automaticamente” (Shift+Tab) — recomeça com todo o contexto disponível para o plano - “Sim, e aprovar as edições manualmente” — preserva o contexto; você aprova cada alteração - “Sim, aceitar as edições automaticamente” — preserva o contexto; Claude executa sem exigir aprovação para cada edição

A limpeza automática do contexto após a aprovação é o fluxo de trabalho recomendado. Ela oferece ao plano uma nova janela de contexto, o que melhora significativamente a fidelidade ao plano — Claude mantém o foco por mais tempo sem a interferência da conversa anterior.

Quando usar o modo de planejamento: - Implementações de novos recursos que envolvem decisões de arquitetura - Refatorações em vários arquivos quando você deseja analisar a abordagem primeiro - Bases de código desconhecidas, nas quais a exploração deve ocorrer antes das alterações - Qualquer tarefa com várias abordagens válidas em que você queira opinar

Dica de especialista: quanto mais tempo você dedicar ao modo de planejamento, maior será a probabilidade de Claude implementar tudo com sucesso. O modo de planejamento oferece uma exploração praticamente sem custo — sem chamadas arriscadas de ferramentas nem edições desperdiçadas. Use-o à vontade.

Modo de leitor de tela (v2.1.208)

Claude Code inclui um modo dedicado de leitor de tela que adapta a interface do terminal para tecnologias assistivas. Ative-o de uma destas três maneiras:¹⁸⁶

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

Anthropic documenta o modo — e seus padrões de interação — em uma nova página de acessibilidade na documentação oficial.¹⁸⁶

Sem pausa antes de cada linha (v2.1.287): agora, o modo de leitor de tela grava linhas novas ou alteradas sem primeiro pausar com o cursor no início da linha. CLAUDE_AX_PREPARK_MS define essa pausa em milissegundos; o valor padrão agora é 0 (antes era 50), portanto, defina CLAUDE_AX_PREPARK_MS=50 para restaurá-la. A mesma versão corrige vários problemas do leitor de tela, incluindo o cursor posicionado longe do texto digitado nas caixas de pesquisa e a ausência de linhas alteradas nas solicitações de aprovação de edições.²³²²³³

Análise aprofundada do sistema de configuração

Claude Code usa um sistema de configuração em camadas. Entender a hierarquia é essencial, porque os níveis mais altos sobrescrevem os mais baixos, e as configurações enterprise não podem ser contornadas de forma alguma.

Hierarquia de configuração

Definindo configurações pelo prompt: /config key=value (v2.1.181)

Desde a v2.1.181, /config key=value define qualquer configuração diretamente no prompt, por exemplo /config thinking=false, sem abrir a interface interativa do /config, e funciona em sessões interativas, -p e Remote Control. /config --help (v2.1.183) lista as chaves abreviadas disponíveis. A v2.1.183 também mudou a interface interativa do /config: agora Enter e Espaço alternam a configuração selecionada, e Esc salva e fecha (antes, Esc revertia as alterações).¹⁷⁴

Referência completa do settings.json

Uma configuração completa que demonstra todas as principais opções:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "claude-opus-5-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-sonnet-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides é útil quando uma equipe tem uma biblioteca grande de skills, mas quer restringir mais o que fica exposto em runtime. Use off para ocultar uma skill tanto do modelo quanto do seletor de slash commands, user-invocable-only para mantê-la acionável pelo nome enquanto a remove da seleção do modelo, e name-only para deixar visível apenas o nome da skill, sem a descrição completa.¹⁵⁶

Configurações mais recentes (v2.1.174–176):

• availableModels / enforceAvailableModels (gerenciada, v2.1.175+): a allowlist availableModels restringe quais modelos uma sessão pode selecionar. Com enforceAvailableModels: true, a allowlist também restringe o modelo Default: um Default que resolveria para um modelo não permitido recorre ao primeiro modelo permitido, e as configurações de usuário/projeto não podem mais ampliar uma lista availableModels gerenciada. Uma correção complementar (v2.1.176) fecha a brecha em que a escolha de um alias podia redirecionar para um modelo bloqueado via ANTHROPIC_DEFAULT_*_MODEL, e agora /fast se recusa a alternar para um modelo fora da allowlist.¹⁷² A partir da v2.1.187, as organizações podem impor restrições de modelo diretamente no seletor /model, em --model, /model e ANTHROPIC_MODEL. Ao selecionar um modelo restrito, aparece a mensagem “restricted by your organization’s settings”.¹⁷⁶
• language (refinamento da v2.1.176): além de definir o idioma das respostas, agora os títulos de sessão são gerados por padrão no idioma da sua conversa. Defina language para fixar um idioma específico para os títulos.¹⁷²
• footerLinksRegexes (v2.1.176): badges de links correspondidos por regex na linha do rodapé, configuráveis nas configurações de usuário ou gerenciadas.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): defina como false para desativar a aceleração da rolagem pela roda do mouse no modo de tela cheia.¹⁷²

Configurações mais recentes (v2.1.207–v2.1.212):

• vimInsertModeRemaps (v2.1.208): remapeamentos de teclas personalizados para o modo de inserção do vim. O exemplo clássico é mapear jj para Escape (veja Modo Vim).¹⁸⁶
• axScreenReader (v2.1.208): ativa o modo de leitor de tela de forma persistente (veja Modo de leitor de tela).¹⁸⁶
• processWrapper (v2.1.208): faz com que todo processo que o Claude Code inicia para si mesmo passe por um executável wrapper, pensado para launchers corporativos (veja Launcher corporativo).¹⁸⁶
• Restrição de origem do autoMode (v2.1.207): a configuração autoMode não é mais lida do .claude/settings.local.json de um repositório. Configure-a em ~/.claude/settings.json. Isso fecha uma brecha pela qual um repositório clonado podia trazer configurações do auto mode.¹⁸⁵

Configurações mais recentes (v2.1.217):

• emojiCompletionEnabled (v2.1.217): autocompletar de shortcodes de emoji no campo do prompt. Digite :heart: para inserir ❤️, ou algo parcial como :hea para ver sugestões. Vem ativado por padrão. Defina como false para desativar.¹⁹⁴

Configurações mais recentes (v2.1.219):

• sandbox.network.strictAllowlist (v2.1.219): bloqueia hosts fora da allowlist para comandos em sandbox sem perguntar, em vez de abrir um diálogo de permissão. Veja Modo sandbox.¹⁹⁶
• workflowSizeGuideline (v2.1.219): define a diretriz consultiva de tamanho de Dynamic workflows a partir de qualquer arquivo de configurações (de usuário, de projeto ou gerenciado), e não apenas pelo /config. Por padrão, os Dynamic workflows usam a diretriz medium (“aim for fewer than 15 agents”). A linha correspondente no /config fica oculta enquanto um arquivo de configurações fornecer o valor. A diretriz é consultiva, não um limite imposto. Veja Subagents.¹⁹⁶

Configurações mais recentes (v2.1.242–243):

• modelPicker (de usuário ou gerenciada, v2.1.242+): organiza o seletor /model com uma lista ordenada e rotulada de modelos. É um objeto com um array options e um Boolean opcional replaceBuiltInOptions. Cada linha do array tem um model obrigatório, além de label e description opcionais. O model é usado literalmente, então aliases, IDs da Anthropic e IDs de Bedrock/Vertex/Foundry/gateway funcionam. Com replaceBuiltInOptions em false (o padrão), as linhas são adicionadas depois da lista nativa. Com true, aparecem apenas as suas linhas, o Default e o modelo que a sessão já está usando. O Claude Code lê essa chave das configurações gerenciadas, de --settings e das configurações de usuário, e a ignora nas configurações de projeto e locais, então um repositório clonado não pode renomear os itens do seletor. A fonte de maior prioridade que definir a chave fornece a lista inteira. Uma allowlist availableModels continua valendo para todas as linhas, e um rótulo muda o que o seletor exibe, não o modelo que roda.²⁵⁰²⁴⁸
• promptCacheTtl / subagentPromptCacheTtl (qualquer arquivo, v2.1.242+): "5m" ou "1h" para cada categoria de requisição. Assim, usuários com chave da API e de provedores de nuvem podem manter um cache de uma hora na conversa principal enquanto os subagents ficam em cinco minutos. Veja Estratégias de cache.²⁵⁰²⁴⁸
• modelPricing (gerenciada, v2.1.243+): os preços contratados por modelo e o multiplicador de desconto de uma organização, usados pelo /cost, pela status line e pelos valores de custo da telemetria no lugar do preço de tabela. Veja Visualizando custos.²⁵⁰

Configurações mais recentes (v2.1.247): - feedbackDrafts (v2.1.247): controla a nova ferramenta SendFeedback: quando algo dá errado em uma sessão, o Claude pode redigir um relatório de feedback para você revisar e enviar a partir do /feedback. Desative essa redação com esta configuração. Veja a linha do /feedback em Comandos de barra.²⁴⁵ - Extensão do formato de spinnerTipsOverride (v2.1.247): as entradas de dicas agora podem ser objetos {id, text, cooldownSessions, priority}, além de strings simples, e o objeto ganha as chaves tipsFile e label. Assim, as organizações podem alternar suas próprias dicas junto com as dicas nativas (o exemplo acima mostra o formato estendido). A referência de configurações agora documenta as novas chaves.²⁴⁵²²⁷

Configurações mais recentes (v2.1.248–251):

• desktopSessionCleanupPeriodDays (v2.1.248): limita por quanto tempo as sessões gravadas pelo desktop ficam isentas da limpeza de transcrições. A correção que acompanha essa opção importa mais do que a própria opção: as sessões do Claude Desktop e do Cowork sumiam depois de cleanupPeriodDays (padrão de 30 dias). Agora a limpeza as preserva enquanto elas estiverem no app, a menos que a política da organização gerencie a retenção.²⁰⁶
• Restrições de env no projeto (v2.1.251): um bloco env em um .claude/settings.json no nível do projeto não pode mais definir CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR nem TMPDIR/TMP/TEMP. Defina essas variáveis no seu shell ou nas configurações de usuário ou gerenciadas, para que um repositório clonado não consiga redirecionar o local onde o Claude Code grava seus arquivos de configuração e temporários.²⁰⁶

Configurações mais recentes (v2.1.257-259):

• timeFormat / timeZone (v2.1.257): controlam como o Claude Code exibe horários, como o relógio de conclusão no fim do turno e os timestamps da transcrição. timeFormat aceita formato de 12 horas, 24 horas, 24 horas em UTC ou um padrão strftime explícito. timeZone define o fuso horário.²¹¹ A referência de configurações agora documenta as duas chaves.²²⁷
• permissions.blockReadsOutsideWorkingDirectories (v2.1.257): recusa de imediato leituras de arquivos fora dos diretórios de trabalho da sessão. Sem essa configuração, o auto mode agora pergunta uma vez antes da primeira leitura desse tipo na sessão (veja Auto Mode).²¹¹ A v2.1.273 fecha duas brechas: um comando Bash que o verificador não consegue analisar por completo agora gera uma solicitação de permissão em vez de pular a verificação, e um diretório de memória escolhido pelas configurações de um repositório não é carregado, recuperado nem indexado com essa configuração ativa.²¹⁷
• managedMcpServers / managedSourcesBehavior: chaves de escopo gerenciado, abordadas em Implantação corporativa. Elas cobrem organizações que fornecem servidores MCP a todos os usuários (v2.1.259) e a mesclagem opcional entre fontes gerenciadas (refinada na v2.1.257).²¹¹²⁴⁴

Configurações mais recentes (v2.1.261):

• bashOutputMaxChars / taskOutputMaxChars (v2.1.261): aumentam quanto da saída de comandos (e da saída de tarefas em segundo plano, respectivamente) o Claude recebe inline antes que o restante seja salvo em um arquivo, até 128 mil caracteres. O mecanismo é diferente da variável de ambiente BASH_MAX_OUTPUT_LENGTH, que define a janela de leitura a partir do arquivo de saída de trabalho do comando (30.000 caracteres por padrão, com limite de 150.000). Essas chaves controlam o limite entre a saída inline e a saída persistida em arquivo: acima dele, a saída vai para um arquivo que o Claude pode ler sob demanda, em vez de ser cortada.²¹⁴ A partir da v2.1.265, o lado persistido também tem um teto: os resultados de ferramentas salvos em disco são limitados a 1 GB, e a prévia na conversa informa quando um arquivo salvo foi truncado.²¹⁵ A parte de tarefas foi aposentada na v2.1.277: a ferramenta obsoleta TaskOutput foi removida. Agora o Claude lê o arquivo de saída de uma tarefa em segundo plano com o Read, e taskOutputMaxChars e TASK_MAX_OUTPUT_LENGTH deixaram de ter efeito. bashOutputMaxChars não foi afetada.²¹⁹

Configurações mais recentes (v2.1.267-269):

• maxEffortLevel (v2.1.267): limita o nível de esforço que os usuários podem escolher, no nível superior ou por modelo em modelSettings, e vale em todos os provedores, incluindo Bedrock, Vertex e Foundry. Os usuários ainda podem escolher um nível abaixo do limite. É o complemento administrativo do /effort.²¹⁶
• advisorModel: o modelo advisor salvo (fable, opus, sonnet ou um ID completo) que o /advisor grava nas configurações de usuário. --advisor o substitui em uma única sessão, e CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 desativa a ferramenta. Veja A ferramenta Advisor.²⁷⁴
• sandbox.allowNestedUserNamespaces (v2.1.305): permite que comandos em sandbox no Linux e no WSL2 criem user namespaces (Chromium, podman sem root). Como isso permite contornar as proteções de arquivos do sandbox, a chave só é lida das configurações de usuário ou gerenciadas. Veja Modo sandbox.²⁷⁸²⁷⁹
• bashEditDiffEnabled (v2.1.269): quando a ferramenta Bash faz uma edição de arquivo, o resultado da ferramenta traz um diff dos arquivos alterados pelo comando, então a conversa mostra o que uma edição no estilo sed realmente fez.²¹⁶

Configurações mais recentes (v2.1.275):

• syncClaudeAiSkills / syncClaudeAiPlugins (v2.1.275): as skills e os plugins ativados na sua conta claude.ai agora são sincronizados com as sessões de terminal conectadas com essa conta. Defina qualquer uma das chaves como false para manter as sessões de terminal apenas com skills e plugins locais. Veja Skills e Sistema de plugins.²¹⁸

Configurações mais recentes (v2.1.282-283):

• maxProseWidth (v2.1.282): limita a largura do texto em prosa do Claude em um terminal largo. Parágrafos, títulos, listas e citações quebram linha dentro desse número de colunas, enquanto tabelas e blocos de código mantêm a largura total. O valor é um número inteiro de colunas, com mínimo de 40.²²⁵²²⁷
• deniedModels / availableModelsMatch (gerenciadas, v2.1.283): deniedModels bloqueia modelos específicos mesmo quando availableModels os permite. Um alias de família como "opus" bloqueia a família inteira, e "claude-opus-5" também bloqueia o Opus 5.5 (use "claude-opus-5-0" para bloquear apenas o Opus 5). Por padrão, uma entrada de availableModels como "claude-opus-5" também permite versões posteriores que a estendem. Com availableModelsMatch: "exact", cada entrada permite apenas a versão que nomeia, então um novo lançamento continua bloqueado até que você o inclua na lista. O Claude Code lê as duas chaves apenas das configurações gerenciadas.²²⁶²²⁷
• allowClaudeInChromeWithManagedMcp (gerenciada, v2.1.282): permite que o claude --chrome rode junto com um managed-mcp.json exclusivo. A mensagem de erro exibida quando o Chrome é bloqueado agora cita a chave.²²⁵ A referência de configurações agora a documenta: a chave é lida apenas das configurações gerenciadas do próprio dispositivo, e uma entrada deniedMcpServers para claude-in-chrome continua bloqueando o servidor.²³³

Configurações mais recentes (v2.1.285):

• allowedProviders (gerenciada, v2.1.285): limita quais provedores de API uma máquina pode usar: a API da Anthropic, um endpoint personalizado, Bedrock, Mantle, Vertex AI, Foundry, Claude Platform na AWS ou um gateway na nuvem.²²⁹ A referência de configurações documenta a chave. Uma lista vinda das fontes administrativas da própria máquina continua valendo quando as configurações gerenciadas pelo servidor também fornecem uma, então uma sessão só pode usar provedores presentes nas duas listas.²³³

Consulta rápida de configurações: as flags mais buscadas

Se você chegou aqui procurando uma configuração específica pelo nome, este é o índice resumido. Cada entrada informa a versão em que foi lançada e, quando um escopo é dono dela, qual é esse escopo:

Onde está a documentação oficial de cada tópico?

Este guia é um manual de campo, não a referência oficial. Quando você precisar da página canônica de Anthropic sobre um subsistema, estes são os endereços oficiais (cada seção deste guia aponta para a sua):

Referência de variáveis de ambiente

Autenticação e API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

Configuração de modelo:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5-5         # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5    # What the `opus` alias resolves to (Opus 5.5 since v2.1.280; Opus 5 v2.1.219-278)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001  # pin the haiku alias; on the Anthropic API it resolves to Haiku 5.5 (claude-haiku-5-5) as of v2.1.293[^274][^275]
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1             # Turn the advisor tool off: /advisor becomes unavailable, advisorModel is ignored, --advisor is accepted but does nothing[^282]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
CLAUDE_CODE_DISABLE_WORKFLOWS=1                 # Turn dynamic workflows off for one session; same effect as "disableWorkflows": true, and whichever of the two turned them off, the other cannot turn them back on. Workflows are on by default except on Pro, where "enableWorkflows": true (the Dynamic workflows row in /config) turns them on; the v2.1.147 opt-in CLAUDE_CODE_WORKFLOWS=1 no longer appears in the env-vars reference[^291]
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_MAX_TURNS=10                        # Cap agentic turns when no --max-turns is passed; the flag wins when both are set, and a value that is not a positive integer is rejected at startup[^291]
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Configuração de provedores de nuvem:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
VERTEX_REGION_CLAUDE_HAIKU_5_5=us-east5          # Vertex region for Claude Haiku 5.5 (v2.1.293+)[^276]
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send the x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted, and prompt-id from v2.1.283) through a gateway or third-party provider; a direct Anthropic API connection sends them by default, and =0 stops them everywhere (v2.1.273+)[^253][^262][^263]
CLAUDE_CODE_AUTO_MODE_SERVER=0                  # Opt out of the server-side auto-mode checks, the default since v2.1.278 for Enterprise and Claude API accounts, Claude Platform on AWS, Bedrock, Agent Platform, Foundry, and gateways (not charged when the server performs them; =1 was the v2.1.273-277 opt-in); also applies on a direct Anthropic API connection since v2.1.281, where server-side is the default with telemetry off since v2.1.282; the docs call it temporary[^253][^255][^259][^260][^261]
CLAUDE_CODE_AUTO_MODE_MODEL=claude-sonnet-5-5   # Model the client-side auto mode classifier uses; no effect on server-side auto mode (v2.1.302+)[^283]

Controle de comportamento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
CLAUDE_CODE_DISABLE_WEB_FETCH=1                 # Turn off the WebFetch tool; WebSearch stays available (v2.1.285+)[^265][^269]
CLAUDE_CODE_DISABLE_ARTIFACT=1                  # Turn the Artifact tool off for one session; while it is set, no settings file turns artifacts back on[^291]
CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0                # Do not open the browser when a new artifact is published[^291]
CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES=2      # Cap re-sends of a non-streaming fallback request that timed out (v2.1.285+)[^265]
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=5000 # Starting delay of the exponential backoff between retries of a 529 overloaded request, default 500; whole milliseconds from 500 to 32000; no effect with CLAUDE_CODE_RETRY_WATCHDOG=1 or in fast mode (v2.1.292+)[^272][^276]
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=60000 # Ceiling of that backoff, default 32000 ms (v2.1.296+; in the env-vars docs since October 14)[^274][^280]
CLAUDE_CODE_RETRY_WATCHDOG=1                     # Unattended sessions: retry 429 and 529 capacity errors indefinitely, backing off up to 5 minutes or until the limit resets (v2.1.186+)[^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000   # Cap, per request, on how long the watchdog waits out 429 and 529 errors; unset means no limit (v2.1.295+)[^274][^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=3600000 # Under the watchdog, end a request at a usage limit that resets further away than this instead of waiting it out (v2.1.301+)[^283]
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS=60000 # Minimum interval between checks that a usage limit was lifted before its reset, while the watchdog waits on it (v2.1.305+)[^286][^287]
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1      # Keep the dangerous-rm prompt waiting in auto mode and --dangerously-skip-permissions instead of denying after 2 minutes (v2.1.281+)[^260]
CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1    # Skip the prompt for a recursive rm whose target is only command-substitution output, such as rm -rf "$(pwd)" (v2.1.281+)[^260]
CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1     # Keep prompting for an rm built at run time inside a shell -c script Claude Code cannot read; such scripts no longer prompt by default (v2.1.299+; release-notes only as of 2026-10-14)[^279][^280]
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=0                     # Turn fork subagents off; on by default in the terminal and, since v2.1.302, in claude -p, the Agent SDK, the desktop app, and VS Code (=1 was the external-build opt-in from v2.1.117; claude mcp serve never offers them)[^160][^283]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+). Since v2.1.290 an interactive session's budget refills instead of ending at 200 (next line); the env-vars docs, fetched Oct 6, still describe the 200 cap[^206][^271][^273]
CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=100     # WebSearch budget refill rate: 100 calls/hour by default in an interactive session, 0 (off) in a non-interactive one (v2.1.290+)[^271][^276]
CLAUDE_CODE_DISABLE_ATTACHMENTS=1               # Send @-mentions as plain text instead of expanding file content; a repo's .claude/settings.json or settings.local.json can no longer set it (v2.1.290)[^271][^273]
CLAUDE_CODE_DISABLE_FILE_MENTIONS=1             # Hand Claude the path of an @ mention to read with its file tools, not the file's contents, so PreToolUse hooks see the read; ignored in project and local settings (v2.1.299+)[^279][^280]
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL=sonnet         # Run every workflow agent on one model while other subagents keep theirs (v2.1.296; release-notes only as of 2026-10-14)[^274][^280]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

Configuração de ferramentas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=8192     # Override the cap on MCP tool descriptions and server instructions, every server in the session: 4,096 chars since v2.1.296, 2,048 in v2.1.280-295; Anthropic's first-party servers at api.anthropic.com are uncut since v2.1.299[^279][^256][^274]
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=10000           # Bound how long the FIRST non-interactive turn waits for still-connecting MCP servers; 0 = don't wait (v2.1.274+)[^254]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Limite de tempo para comandos em segundo plano (v2.1.285, restringido na v2.1.288): comandos Bash e PowerShell em segundo plano são interrompidos após um limite de tempo, o timeout deles quando executados com run_in_background (padrão de 30 minutos, máximo de 2 horas), e Claude é notificado quando um deles é interrompido.²²⁹ A partir da v2.1.288, o limite se aplica apenas a sessões não supervisionadas (-p, o Agent SDK, CI e sessões na nuvem); sessões no terminal, no app desktop e no VS Code não têm limite para comandos em segundo plano. A referência de ferramentas confirma: “Antes da v2.1.288, ele se aplicava a todas as sessões.”²³⁴²³⁷

Rede e proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
CLAUDE_CODE_GZIP_REQUEST_BODIES=0              # Turn off gzip compression of large request bodies sent to api.anthropic.com, on even with telemetry off since v2.1.300[^281][^282]
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI e terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory; not settable from project-settings env (v2.1.251)[^238]
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope); also the opt-out for the v2.1.287 1M default on Bedrock/Vertex/Foundry/Claude apps gateway[^103][^217][^268]
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200k           # Auto-compact window, 100000 to 1000000 tokens; k and M suffixes since v2.1.304 (200k had set a 100K window), out-of-range values warn[^286][^287]
CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1  # Let claude ultrareview run in a folder you have not trusted where it cannot ask, such as CI; environment only, not a settings env block (v2.1.309+)[^286][^287]
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=150000     # Context size at which idle compaction applies, default 200000; values below 100000 are raised to 100000; "idleCompaction": false in settings.json turns the feature off (v2.1.299; the docs date both to v2.1.290+)[^279][^280]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
CLAUDE_AX_PREPARK_MS=50                       # Screen reader mode: pause before writing a changed line; default 0 since v2.1.287 (was 50)[^268][^269]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

Exportadores OpenTelemetry + controle de campos sensíveis:²⁶⁸

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+); as of v2.1.273 also puts real agent, skill, plugin, and MCP server names on cost and token metrics[^253]
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
OTEL_METRICS_INCLUDE_REPOSITORY=1             # Tag OTel metrics and events with vcs.* repository attributes; with OTEL_LOG_TOOL_DETAILS, commit events carry vcs.ref.head.* (v2.1.269+)[^252]
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set; v2.1.290 also skips the startup connection warm-up[^271]
CLAUDE_CODE_ATTRIBUTION_HEADER=0              # Omit the system-prompt attribution block; behind a Claude apps gateway, set it in the env of the gateway's code or cli policy (v2.1.299+)[^279][^280]

O projeto não pode ativar a telemetria (v2.1.282): os arquivos de configurações de projeto e locais agora ignoram as variáveis do OpenTelemetry que ativam a exportação, definem seu endpoint ou capturam conteúdo, como CLAUDE_CODE_ENABLE_TELEMETRY, os seletores OTEL_*_EXPORTER e OTEL_LOG_*. Valores que desativam algo (none para um seletor de exporter, 0 para uma flag de conteúdo) continuam valendo a partir desses arquivos. Defina as demais no seu shell, nas configurações de usuário ou nas configurações gerenciadas. Uma sessão interativa exibe um aviso na inicialização quando um arquivo de projeto define uma delas, e /status e claude doctor listam os nomes ignorados; sessões -p e do Agent SDK não exibem aviso, então confira se o seu coletor continua recebendo dados depois de atualizar.²²⁵²²⁷

Atributos de span por requisição LLM (v2.1.121+): stop_reason, gen_ai.response.finish_reasons e user_system_prompt agora são emitidos nos spans de requisição LLM. user_system_prompt fica condicionado a OTEL_LOG_USER_PROMPTS=1, já que pode conter PII.¹⁵⁴

Mudanças em nível de evento (v2.1.122+): atributos numéricos nos eventos de log api_request e api_error agora são emitidos como números (antes eram strings), o que corrige coletores OTel downstream que tipavam o schema de forma estrita. O novo evento de log claude_code.at_mention é disparado quando o Claude Code resolve uma menção com @.¹⁵⁴

Atributos da v2.1.300: os eventos api_request separam as gravações de cache em cache_creation_5m_tokens e cache_creation_1h_tokens; os spans de trace trazem atributos da convenção semântica GenAI (gen_ai.provider.name, gen_ai.conversation.id, gen_ai.tool.name, error.type); os eventos user_prompt e os spans de interação registram o prompt na forma em que o hook prompt.submit de um mod o reescreveu; e os eventos tool_result trazem git_commit_id após git commit -q em repositórios reftable.²⁷³

Atributos das v2.1.301 e v2.1.302: os eventos tool_decision trazem classifier_verdict e permission_mode, para que uma decisão do classificador do auto mode possa ser diferenciada de uma regra de permissão, e, com OTEL_LOG_TOOL_DETAILS=1, classifier_category, que nomeia a regra embutida que um bloqueio do classificador acionou (v2.1.301); a v2.1.302 preenche classifier_category na maioria dos bloqueios do classificador, onde antes faltava, e mantém tool_use_id, tool_source e tool_parameters no evento quando OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT está baixo. A documentação de monitoramento ainda não lista esses três atributos.²⁷⁵²⁷⁶

Evento da v2.1.307: claude_code.safety_event é disparado para cada chamada de ferramenta que uma regra de permissão, o auto mode, uma verificação de segurança, um hook ou o sandbox interrompeu, submeteu a confirmação ou devolveu; tool_use_id está presente nele, exceto em eventos de fim de turno. A documentação de monitoramento o lista e agora também lista classifier_verdict (v2.1.301+).²⁷⁸²⁷⁹

Evento de log claude_code.assistant_response (v2.1.193+): o Claude Code pode emitir o texto completo da resposta do modelo como um evento de log OTel, condicionado a OTEL_LOG_ASSISTANT_RESPONSES. Esse condicionamento tem uma pegadinha de atualização que vale conhecer: quando OTEL_LOG_ASSISTANT_RESPONSES não está definida, ela segue OTEL_LOG_USER_PROMPTS, então qualquer implantação que já registre o conteúdo dos prompts passará a receber o conteúdo das respostas do assistente ao atualizar. Defina OTEL_LOG_ASSISTANT_RESPONSES=0 para manter a telemetria restrita aos prompts.¹⁷⁹

Adições de telemetria da v2.1.214: os eventos de log OTel agora trazem os atributos message.uuid, client_request_id e tool_source, para correlação em nível de mensagem e procedência das ferramentas; o payload subagentStatusLine inclui o reasoning effort do subagent, para que linhas personalizadas da status line possam exibir modelo e effort juntos; e a nova variável de ambiente CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH configura o limite de truncamento de 60 KB nos atributos de conteúdo OTel.¹⁹⁰

Telemetria do gateway (v2.1.265): as sessões do gateway de apps Claude agora exportam OpenTelemetry diretamente para um coletor quando as configurações gerenciadas do gateway indicam um em OTEL_EXPORTER_OTLP_ENDPOINT, em vez de passar pelo relay do gateway; sessões sem um coletor indicado continuam usando o relay. A mesma versão adiciona user.email e user.groups à telemetria que o Claude Desktop e o Cowork enviam por meio de um gateway de apps Claude, igualando as sessões de terminal.²¹⁵

Telemetria de hooks (v2.1.280): o evento OTel hook_execution_complete agora traz os tamanhos das saídas dos hooks e o número de saídas grandes demais que foram salvas em um arquivo.²²⁰

prompt_text (v2.1.287): o evento user_prompt agora traz prompt_text, uma cópia de prompt para backends que aninham chaves com pontos. Onde quer que o seu pipeline descarte ou mascare prompt, faça o mesmo com prompt_text.²³²

API / Controle de modelo:²⁶⁸

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+); a Read call with allow_large can pass it when the context has room (v2.1.296+)[^274][^276]
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1      # Stop sending structured outputs, for Mantle or gateways that reject them; session titles, memory recall, and prompt hooks failed there before (v2.1.288+)[^270][^273]
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:²⁶⁸

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)
MCP_SDK_GENERATION=v1                         # Opt out of the v2 MCP client; v2.1.274 made v2 the default on the last holdouts (Bedrock/Vertex/Foundry + telemetry-disabled installs)[^254]
MCP_PROTOCOL_NEGOTIATION=legacy               # Opt out of MCP 2026-07-28 protocol negotiation: with direct HTTP servers (default everywhere as of v2.1.274) and, since v2.1.292, with local (stdio) servers on every install, Bedrock, Vertex, and Foundry included and, since v2.1.299, with cloud session and Remote Control connectors[^279][^254][^272]

Shell / IDE:²⁶⁸

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

Enterprise / autenticação:²⁶⁸

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Variáveis de skills (v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

Identidade do chamador SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=user@example.com        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Depuração:

ANTHROPIC_LOG=debug                             # Enable API request logging

Qual modelo devo escolher?

Escolher o modelo certo para cada tarefa tem um impacto significativo tanto no custo quanto na qualidade. O Claude Code permite alternar entre modelos de forma flexível em vários níveis.

Modelos disponíveis

Claude Sonnet 5.5 (28 de setembro de 2026): O modelo Sonnet padrão na Anthropic API desde a v2.1.284, que direciona o alias sonnet para ele; o modelo padrão em todos os planos continua sendo o Opus 5.5. ID do modelo: claude-sonnet-5-5 (Bedrock: anthropic.claude-sonnet-5-5). $2/MTok de entrada, $10/MTok de saída, o mesmo preço do Sonnet 5, com leituras de cache a $0,10/MTok (0,05x o preço de entrada segundo a página de preços, a mesma proporção do Opus 5.5; a v2.1.296 corrige os valores de custo do próprio Claude Code, que usavam $0,20). Janela de contexto de 1M de tokens, saída máxima de 128 mil (até 300 mil na Batches API com o cabeçalho beta output-300k-2026-03-24). Data de corte do conhecimento confiável: junho de 2026, a mesma do Opus 5.5 e do Fable 5.1. Descontinuação não antes de 28 de setembro de 2027. No Claude Code, effort usa medium por padrão no Sonnet 5.5 (o padrão da própria Claude API é high), e o raciocínio não pode ser desativado. Fallback baseado no conteúdo: uma requisição sinalizada por questões de cibersegurança é executada novamente no Sonnet 5, e uma requisição sinalizada por questões de biologia termina com uma recusa porque o Sonnet 5.5 não tem um modelo de fallback para biologia. Requer o Claude Code v2.1.284 ou posterior; para continuar no Sonnet 5, fixe ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5.²²⁸²³⁰

A página do modelo lista cinco mudanças incompatíveis para código da API que migra do Sonnet 5: o raciocínio inicial é desativado com between_tools, o uso forçado de ferramentas retorna um erro, os blocos de raciocínio ficam vinculados ao modelo e à conversa, computer_20251124 não é aceito na Claude API e no Google Cloud, e a ferramenta de assessoria rejeita Opus 4.8, Opus 4.7 e Sonnet 5 como assessores. O texto entre chamadas de ferramentas também retorna em blocos thinking, então uma interface que o exibe em streaming deixa de mostrar esse texto até definir um valor de display que o retorne.²³⁰

Claude Opus 5.5 (22 de setembro de 2026): O novo modelo Opus padrão no Claude Code desde a v2.1.280 – e, segundo a tabela por plano da documentação de configuração de modelos, o modelo padrão em todos os planos e provedores próprios: Pro, Max, Team, Enterprise, a Anthropic API, a Claude Platform on AWS, o Amazon Bedrock e o Agent Platform do Google Cloud (o Microsoft Foundry continua no Sonnet 4.5, e seu alias opus aponta para o Opus 4.6). A mesma versão muda o padrão do Pro e do Team Standard de Sonnet para Opus, “alinhando-os ao Max, Team Premium e Enterprise” – encerrando a divisão entre planos que existia desde que a categoria premium migrou para o Opus. ID do modelo: claude-opus-5-5 (Bedrock: anthropic.claude-opus-5-5) – uma versão fixa sem data, no mesmo esquema de claude-opus-5. O preço fica abaixo do Opus 5: $4/MTok de entrada, $20/MTok de saída (Opus 5: $5/$25), com leituras de cache a $0,20/MTok – 5% do preço de entrada, metade dos 10% padrão (apenas Fable 5.1 e Mythos 5.1 têm uma proporção menor, de 2,5%). Janela de contexto de 1M de tokens, saída máxima de 128 mil (até 300 mil na Batches API com o cabeçalho beta output-300k-2026-03-24). Raciocínio adaptativo sempre ativo – a tabela de visão geral dos modelos usa a mesma designação “Adaptativo (sempre ativo)” do Fable, em vez do comportamento do Opus 5, ativo por padrão, mas que pode ser desativado. effort usa medium por padrão (o Opus 5 usava high), e a v2.1.280 ajusta a regra de reaproveitamento dessa configuração: um nível de esforço salvo antes de /effort passar a ser definido por modelo não se aplica mais a modelos recém-lançados, como o Opus 5.5 – o modelo começa com seu próprio padrão até você escolher um nível. Data de corte do conhecimento confiável: junho de 2026 (dados de treinamento também de junho de 2026), empatando com o Fable 5.1 como a mais recente entre todos os modelos atuais. Descontinuação não antes de 22 de setembro de 2027. Requer o Claude Code v2.1.280 ou posterior.²²⁰²²¹

Mudanças incompatíveis ao migrar código da API do Opus 5 para o Opus 5.5:²²²

1. O raciocínio não pode ser desativado. Tanto thinking: {type: "disabled"} quanto thinking: {type: "enabled", budget_tokens: N} retornam um erro 400. Remova o campo thinking e escolha um nível de esforço.
2. O uso forçado de ferramentas retorna um erro. tool_choice aceita apenas auto e none; any e tool retornam um erro 400, inclusive no endpoint de contagem de tokens. Use auto com uso estrito de ferramentas ou saídas estruturadas.
3. Os blocos de raciocínio ficam vinculados ao modelo. Um roteador ou fallback que transfere uma conversa do Opus 5.5 para outro modelo executa esses turnos sem os blocos de raciocínio do Opus 5.5 (Fable 5.1 e Mythos 5.1 na Claude API são a exceção).
4. computer_20251124 é rejeitado na Claude API e no Google Cloud. Declare o conjunto de ferramentas computer_toolset_20260801 em seu lugar; o Bedrock mantém a ferramenta anterior. Outra mudança não faz nenhuma requisição falhar, mas altera o formato da resposta: o texto que o modelo escreve entre chamadas de ferramentas retorna em blocos thinking, vazios na configuração padrão de display. Uma interface que transmite essa narração fica em silêncio até definir display: "updates" (beta) ou "summarized".²²²

Fallback baseado no conteúdo no Claude Code. O Opus 5.5 opera com classificadores de segurança que sinalizam com mais frequência conteúdos de biologia e cibersegurança. Quando um deles sinaliza uma requisição, o Claude Code a executa novamente em outro modelo e exibe um aviso: requisições sinalizadas por biologia vão para o Opus 5, as sinalizadas por cibersegurança vão para o Opus 4.8, e a sessão permanece no modelo de fallback até você voltar ao anterior com /model. Desative Trocar de modelo quando uma mensagem for sinalizada em /config (switchModelsOnFlag: false) para que sua confirmação seja solicitada a cada vez.²²³ Desde a v2.1.287, a troca mantém seu nível de esforço atual em vez de usar o padrão do modelo de fallback. Assim, uma sessão no nível medium, padrão do Opus 5.5, permanece em medium no Opus 4.8, cujo padrão é high.²³²²³³

Claude Opus 5 (julho de 2026; categoria Opus anterior): A categoria Opus e o modelo para o qual o alias opus apontava desde a v2.1.219 (24 de julho de 2026) até a v2.1.280 tornar o Opus 5.5 o modelo Opus padrão; o que segue descreve seu lançamento em julho de 2026. A Anthropic o apresenta como uma atualização que substitui diretamente o Opus 4.8: os mesmos US$ 5/MTok de entrada e US$ 25/MTok de saída, “desempenho muito superior pelo mesmo custo” e, em média, cerca de 26% menos tokens no nível máximo de raciocínio que o Opus 4.8. Ele era o modelo padrão no Claude Max e o modelo mais potente no Claude Pro. ID do modelo: claude-opus-5 — um snapshot fixo sem data, no mesmo esquema de claude-opus-4-8 e claude-sonnet-5, e não uma referência atualizada continuamente. Janela de contexto de 1 milhão de tokens (sem cabeçalho beta, sem alterações em relação ao Opus 4.8), saída máxima de 128 mil tokens (até 300 mil na API Batches com o cabeçalho beta output-300k-2026-03-24). Apenas raciocínio adaptativo — o raciocínio estendido com thinking.type: "enabled" não é compatível. Data de corte do conhecimento confiável: maio de 2026 (os dados de treinamento também têm corte em maio de 2026) – a mais recente entre todos os modelos atuais do Claude, desde seu lançamento até a chegada do Fable 5.1 (com corte em junho de 2026) em 1º de setembro de 2026.²⁴¹ Com a chegada do Opus 5, o Opus 4.8 passa para a tabela de modelos legados da documentação, ao lado do 4.7 e do 4.6 — continua disponível, mas deixa de ser o padrão recomendado.¹⁹⁷

Duas mudanças que quebram a compatibilidade ao migrar um harness do Opus 4.8 para o Opus 5:¹⁹⁷

1. O raciocínio vem ativado por padrão. No Opus 4.8, uma requisição sem o campo thinking era executada sem raciocínio; no Opus 5, a mesma requisição usa raciocínio adaptativo. max_tokens continua sendo um limite rígido para a saída total — raciocínio mais texto da resposta —, então confira novamente a margem disponível em qualquer carga de trabalho que antes rodava sem raciocínio. Passe thinking: {type: "disabled"} para restaurar o comportamento anterior, observando a restrição do próximo item.
2. Desativar o raciocínio limita o esforço a high. Combinar thinking: {type: "disabled"} com esforço xhigh ou max retorna um 400. A verificação ocorre a cada requisição — elevar o esforço para xhigh com o raciocínio desativado é rejeitado, mesmo que turnos anteriores da mesma conversa tenham sido aceitos.

Especificamente no Claude Code: o padrão de effort no Opus 5 é high (assim como na API do Claude), e todos os níveis estão disponíveis — low, medium, high, xhigh, max. A própria orientação de migração da Anthropic é testar o esforço max quando a capacidade importa mais que o gasto com tokens. O modo rápido inclui o Opus 5 a US$ 10/US$ 50 por MTok (veja Modo rápido).¹⁹⁷¹⁹⁸

Claude Fable 5.1 (1º de setembro de 2026): O novo topo da categoria Fable e, desde a v2.1.257, o modelo para o qual o alias fable aponta (a menos que ANTHROPIC_DEFAULT_FABLE_MODEL fixe outro modelo); best agora significa “o modelo Fable mais recente disponível para você”. A versão mínima precisa de um esclarecimento: a documentação de configuração de modelos diz que o alias mudou na v2.1.255, e a página do modelo diz que o Fable 5.1 “requer Claude Code v2.1.255 ou posterior”, mas as versões 2.1.253-256 nunca foram publicadas no npm – a v2.1.257 (1º de setembro) é a primeira versão instalável que o inclui. ID do modelo: claude-fable-5-1 (Bedrock: anthropic.claude-fable-5-1). Mesma categoria e mesmo preço por token do Fable 5 – US$ 10/MTok de entrada, US$ 50/MTok de saída, contexto de 1 milhão de tokens, saída máxima de 128 mil tokens, raciocínio adaptativo sempre ativado, effort com padrão high – com uma mudança de preço relevante para sessões longas de agentes: leituras de cache custam US$ 0,25/MTok, 0,025 vez o preço de entrada (2,5%), contra os 10% padrão; apenas o Fable 5.1 e o Mythos 5.1 têm essa tarifa, e as gravações no cache mantêm os preços padrão (US$ 12,50 para 5 minutos, US$ 20 para 1 hora). Data de corte do conhecimento confiável: junho de 2026 (os dados de treinamento também são de junho de 2026) – a mais recente entre todos os modelos atuais do Claude, igualada pelo Opus 5.5 (com corte em junho de 2026) em 22 de setembro de 2026 e pelo Sonnet 5.5 em 28 de setembro. Descontinuação não antes de 1º de setembro de 2027. Desde a v2.1.301, quando o modelo Fable mais recente não está disponível para sua organização, fable e best tentam novamente uma vez com o modelo Fable anterior em vez de retornar um erro.²⁷⁵

Três mudanças que quebram a compatibilidade com o Fable 5: forçar o uso de ferramentas retorna um erro, modelos anteriores não conseguem ler seus blocos de raciocínio, e editar turnos anteriores invalida os blocos de raciocínio. Cinco adições: esforço por mensagem (beta), mensagens de sistema com escopo limitado ao turno (beta), atualizações de progresso entre chamadas de ferramentas (display: "updates", beta), leituras de cache mais baratas e proveniência do conteúdo. O Claude Mythos 5.1 é o mesmo modelo, com as mesmas especificações, disponível apenas por convite via Project Glasswing. Com o lançamento, o Fable 5 passa para a tabela de modelos legados da documentação, ao lado do Opus 4.8/4.7/4.6/4.5 e do Sonnet 4.6/4.5.

Uma ressalva sobre o gateway nas notas de versão: nas sessões pelo gateway de aplicativos do Claude, fable e best continuam apontando para o Fable 5 por enquanto – um gateway ainda não configurado para o 5.1 o rejeita –, então selecione explicitamente o Fable 5.1 em /model nessas sessões; observe que, antes da v2.1.260, o seletor /model não listava o Fable 5.1, então selecioná-lo explicitamente exigia digitar o comando completo /model claude-fable-5-1 (veja as correções pós-lançamento abaixo). Padrões dos planos no lançamento: Opus 5 nos planos premium, Sonnet 5 no Pro e no Team Standard – substituídos pelo padrão Opus 5.5 em todos os planos na v2.1.280 (22 de setembro de 2026).^211241242221

Correções pós-lançamento do Fable 5.1 (v2.1.260, 3 de setembro): a primeira versão após o lançamento corrige quatro problemas. O seletor /model agora mostra o Fable 5.1 para organizações que podem usá-lo – antes dessa correção, o modelo só era aceito quando digitado por extenso como /model claude-fable-5-1. O cache de prompts no Fable 5.1 agora inclui o contexto anexado após os resultados das ferramentas, que antes era reenviado como entrada sem cache em todo turno com chamada de ferramenta – reduzindo silenciosamente a economia das leituras de cache a 0,025 vez o preço de entrada justamente nas sessões longas de agentes para as quais foram criadas. Alterar /effort no meio da sessão não invalida mais o cache de prompts. E agentes com model: fable agora respeitam a tag [1m] em um modelo fixado por ANTHROPIC_DEFAULT_FABLE_MODEL, em vez de usar silenciosamente uma janela de contexto de 200 mil tokens.²¹²

Claude Fable 5 (9 de junho de 2026; legado desde 1º de setembro de 2026): Uma nova categoria de modelo acima do Opus — o modelo mais poderoso e inteligente da Anthropic, com desempenho de ponta em quase todos os benchmarks em que foi testado e projetado para manter a coerência ao longo de milhões de tokens de contexto. O Fable 5 é o modelo de fronteira da “classe Mythos” adaptado para uso geral seguro: ele inclui classificadores de segurança que recorrem ao Opus 4.8 em consultas sobre cibersegurança, biologia e química e destilação de modelos (o Claude Mythos 5 é o mesmo modelo com essas salvaguardas removidas para pesquisadores autorizados). Ele passou a estar disponível para seleção no Claude Code com a v2.1.170 (9 de junho de 2026) — execute claude update, depois /model fable (o alias curto, que desde a v2.1.257 aponta para o Fable 5.1 – para selecionar o Fable 5 hoje, use /model claude-fable-5) — e sua disponibilização nos planos de assinatura foi concluída em 22 de junho de 2026. ID do modelo: claude-fable-5. O Fable 5 inclui uma janela de contexto de 1 milhão de tokens por padrão, então o sufixo [1m] é desnecessário — e, desde a v2.1.173 (11 de junho de 2026), o nome de modelo claude-fable-5[1m] é normalizado automaticamente para claude-fable-5, removendo o sufixo (ele só tinha utilidade no Opus/Sonnet, que exigem [1m] para habilitar 1 milhão de tokens); saída máxima de 128 mil tokens. O preço é de US$ 10/MTok de entrada e US$ 50/MTok de saída — cerca de 2× o do Opus 4.8 —, então reserve-o para tarefas de raciocínio realmente difíceis, não para edições rotineiras. Ele usa os mesmos parâmetros de requisição do Opus 4.8 (apenas raciocínio adaptativo; temperature/top_p/top_k e budget_tokens removidos), com uma nova particularidade: definir explicitamente thinking: {type: "disabled"} retorna um 400, então omita totalmente o parâmetro thinking para executar sem raciocínio.²⁶¹ Especificamente no Claude Code: o Fable 5 oferece suporte à escala completa de esforço (low/medium/high/xhigh/max, com high por padrão), assim como o Opus 5. Não é possível desativar o raciocínio no Fable 5 — o controle de raciocínio da sessão, a configuração alwaysThinkingEnabled e MAX_THINKING_TOKENS=0 não têm efeito; ele sempre raciocina de forma adaptativa. O conjunto completo de configurações da família fable espelha os controles do Opus: ANTHROPIC_DEFAULT_FABLE_MODEL fixa o modelo para o qual o alias fable aponta (útil no Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE desativa o cache de prompts para o Fable, e o fallback automático baseado em conteúdo se aplica aos gateways empresariais. /model opus agora seleciona o Opus 5.5 (v2.1.280; esforço medium por padrão, /effort xhigh para as tarefas mais difíceis), e o modelo padrão inicial não depende mais do seu plano – o Opus 5.5 é o padrão em todos os planos operados pela Anthropic, com exceção do Microsoft Foundry; escolha explicitamente a categoria Fable via /model fable quando quiser o máximo de capacidade – o que, desde a v2.1.257, significa Fable 5.1.^{261197207242220221}

Opus 4.7 (16 de abril de 2026): O modelo mais avançado da geração anterior, ainda totalmente disponível. Janela de contexto de 1M de tokens com preço padrão — sem cobrança adicional por contexto longo. Saída máxima de 128K, apenas raciocínio adaptativo (o raciocínio estendido foi removido) e um novo nível de esforço xhigh, recomendado como ponto de partida para programação e tarefas com agentes.¹⁴⁵ Data de corte do conhecimento confiável: janeiro de 2026. Data de corte dos dados de treinamento: janeiro de 2026. ID do modelo: claude-opus-4-7. O preço é igual ao do Opus 4.6: US$ 5/US$ 25 por MTok, com gravação em cache de 5 minutos a US$ 6,25, gravação em cache de 1 hora a US$ 10 e leitura do cache a US$ 0,50 por MTok.¹⁴⁴ O Opus 4.7 resolve 3× mais tarefas de produção no SWE-Bench do que o Opus 4.6, alcança 70% no CursorBench (contra 58% do 4.6) e aumenta em 13% a taxa de resolução no benchmark interno de programação da Anthropic, composto por 93 tarefas.¹⁴⁴ Usa um novo tokenizador — espere contagens de tokens de aproximadamente 1×–1,35× para o mesmo texto; aumente a margem de max_tokens e ajuste os limites que acionam a compactação.¹⁴⁵ A capacidade de visão aceita imagens de até 2.576 px / 3,75 MP com coordenadas de pixels em proporção 1:1.¹⁴⁵

Benchmarks de programação do Opus 4.7 (abril de 2026):¹⁵¹

Modelo padrão por plano (Claude Code):²⁰⁷²²¹

Desde a v2.1.280 (22 de setembro de 2026), não há mais distinção por plano: todos os planos operados pela Anthropic e provedores próprios usam o Opus 5.5 por padrão, e a única exceção restante é o Microsoft Foundry. A pergunta que antes mais importava aqui – “qual é o meu plano?” – não muda mais a resposta.

Mudanças incompatíveis na Messages API com o Opus 4.7 (visíveis para quem faz as chamadas):¹⁴⁵

• O budget_tokens do raciocínio estendido foi removido. Use thinking: {type: "adaptive"} no lugar. O raciocínio adaptativo fica desativado por padrão; solicitações sem o campo thinking são executadas sem raciocínio.
• Definir temperature, top_p ou top_k com um valor diferente do padrão retorna HTTP 400. Omita esses parâmetros e oriente o modelo por meio de prompts.
• O conteúdo do raciocínio é omitido das respostas por padrão. Defina thinking.display: "summarized" para voltar a exibir o raciocínio (necessário se o seu produto transmite o raciocínio aos usuários em tempo real).

Os orçamentos de tarefa (cabeçalho beta task-budgets-2026-03-13) permitem informar ao modelo uma meta de tokens para um ciclo completo de execução do agente via output_config.task_budget; mínimo de 20K tokens.¹⁴⁵

Opus 4.6 (legado): Ainda disponível como claude-opus-4-6, com contexto de 1M e saída máxima de 128K. Considere migrar para o Opus 4.7 para melhorar a programação com agentes. O Opus 4.6 foi lançado originalmente em 5 de fevereiro de 2026.⁷⁹¹⁴⁴ Desde a v2.1.117 (22 de abril de 2026), assinantes Pro e Max usam o esforço high por padrão no Opus 4.6 e no Sonnet 4.6 (antes, medium); o Opus 4.7 continua em xhigh. Essa mudança restaurou a capacidade de raciocínio após a redução de esforço de 4 de março → 7 de abril, documentada na análise pós-incidente de 23 de abril.¹⁵²¹⁵³

Sonnet 5 (30 de junho de 2026; geração anterior da linha Sonnet): O modelo que o alias sonnet selecionava na Anthropic API desde a v2.1.197 até a v2.1.284, quando passou a apontar para o Sonnet 5.5. No lançamento, a Anthropic o apresentou como “a melhor combinação de velocidade e inteligência”. A Anthropic afirma que seu desempenho é próximo ao do Opus 4.8, mas com preços menores, e que ele representa uma melhoria substancial em relação ao Sonnet 4.6 em raciocínio com agentes, uso de ferramentas, programação e trabalho intelectual — ao mesmo tempo que apresenta uma taxa geral menor de comportamentos indesejáveis e uma capacidade em cibersegurança muito inferior à dos modelos Opus (a contrapartida de segurança que permitiu seu lançamento sem bloqueios de controle de exportação). ID do modelo: claude-sonnet-5 (snapshot fixo sem data). Janela de contexto de 1M de tokens, saída máxima de 128K (até 300K na Batches API com o cabeçalho beta output-300k-2026-03-24), apenas raciocínio adaptativo. Data de corte do conhecimento confiável: janeiro de 2026. Preço: US$ 2/US$ 10 por MTok de entrada/saída, agora o preço padrão de tabela. A Anthropic anunciou US$ 2/US$ 10 no lançamento como preço introdutório até 31 de agosto de 2026 e depois o manteve: a página de preços informa que o aumento previsto para 1º de setembro, para US$ 3/US$ 15, “não ocorrerá”, e a v2.1.243 atualizou o seletor /model e a skill claude-api incluída para mostrar US$ 2/US$ 10 como preço de tabela, em vez de uma promoção por tempo limitado.²⁵¹ Isso é 50% abaixo dos US$ 4/US$ 20 do Opus 5.5 (e 60% abaixo dos US$ 5/US$ 25 cobrados pelo Opus 5). No Claude Code, o parâmetro effort usa high por padrão no Sonnet 5 (defina-o explicitamente para alterar). Selecione-o com /model claude-sonnet-5.¹⁸⁰²³⁰

A v2.1.197 (30 de junho de 2026) tornou o Sonnet 5 o modelo padrão no Claude Code para novas sessões na época, e ele permaneceu nos planos padrão (Pro, Team Standard) até que a v2.1.280 migrou esses planos para o Opus em 22 de setembro de 2026. O Sonnet 5 não é mais o padrão de nenhum plano no Claude Code, e desde a v2.1.284 /model sonnet seleciona o Sonnet 5.5 na Anthropic API; /model claude-sonnet-5 ou ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 mantém você no Sonnet 5. Consulte a tabela de planos acima.^{181207220221228}

Sonnet 4.6 (17 de fevereiro de 2026, agora sucedido pelo Sonnet 5): Modelo equilibrado; substituiu o Sonnet 4.5 como padrão no claude.ai e no Claude Cowork.⁹³ Mesmo preço do Sonnet 4.5 (US$ 3/US$ 15 por MTok). Melhor desempenho em buscas com agentes, consumindo menos tokens. Oferece suporte a raciocínio estendido, raciocínio adaptativo e uma janela de contexto de 1M de tokens (beta). Saída máxima de 64K (limite superior de 128K na v2.1.77).¹¹⁹ Data de corte do conhecimento: agosto de 2025 (confiável), janeiro de 2026 (dados de treinamento). ID do modelo: claude-sonnet-4-6. Claude Mythos Preview (7 de abril de 2026): Um modelo de ponta em prévia de pesquisa para trabalhos de cibersegurança defensiva, oferecido pelo Project Glasswing.¹³⁹ Disponível apenas por convite; sem disponibilidade geral. A Anthropic apresenta o Opus 4.7 como deliberadamente menos capaz que o Mythos em aspectos de cibersegurança — uma concessão em favor da segurança — e abriu um Cyber Verification Program em https://claude.com/form/cyber-use-case para pesquisadores de segurança legítimos que precisam de acesso ampliado.¹⁴⁶

Por que essas diferenças de preço importam: Uma sessão típica de programação consome de 50 mil a 200 mil tokens de entrada e de 10 mil a 50 mil tokens de saída. Com o Haiku 5.5 nas tarifas para prompts de até 100 mil tokens, isso dá cerca de US$ 0,01 a US$ 0,05 por sessão. Com o Opus 5.5 a US$ 4/US$ 20, a mesma sessão custa de US$ 0,40 a US$ 1,80, cerca de 40 vezes mais (antes dos descontos de cache de prompts). Use o Sonnet ou o Haiku quando a tarefa não exigir o Opus.¹²²²

Quando usar cada modelo

Haiku: Use para subagents que fazem exploração, buscas simples em arquivos e perguntas rápidas. Nas tarifas para prompts de até 100 mil tokens, ele é cerca de 40 vezes mais barato que o Opus 5.5 (8 vezes em um prompt acima de 100 mil) e responde mais rápido. Ideal para tarefas em segundo plano que não exigem raciocínio profundo.

Sonnet: A opção para o desenvolvimento diário quando o custo importa – Sonnet 5.5 na API da Anthropic desde a v2.1.284, pelos mesmos US$ 2/US$ 10 do Sonnet 5²²⁸ – e, desde que a v2.1.280 migrou os planos Pro e Team Standard para o Opus, deixou de ser o padrão de qualquer plano (contexto nativo de 1 milhão de tokens, preço de tabela padrão de US$ 2/US$ 10 por milhão de tokens; o aumento previsto para 1º de setembro foi cancelado).^181251207220 Essa é a mudança que você precisa assimilar: agora o Sonnet é algo que você escolhe, e o motivo para escolhê-lo é matemático – metade do custo por token do Opus 5.5 com o mesmo contexto de 1 milhão de tokens. Dá conta da maioria das tarefas de programação: implementar recursos, corrigir bugs, escrever testes e revisar código. Histórico: por muito tempo, foi divulgado – inclusive aqui – que a v2.1.197 (30 de junho de 2026) havia tornado o Sonnet 5 o padrão em todos os planos, mas o histórico por plano na documentação de configuração de modelos mostra que o padrão premium/da API apontava para o Opus 4.8 desde a v2.1.154 e para o Opus 5 desde a v2.1.219. Portanto, “em todos os planos” se referia, na verdade, à categoria padrão – e a v2.1.280 encerrou até isso. O Sonnet 4.6 ocupou o posto de Sonnet até junho de 2026.^93147207221 Use o Sonnet quando precisar de tokens mais baratos, menor latência ou economia com subagents.

Opus: A categoria de raciocínio profundo — desde a v2.1.280, o alias opus seleciona o Claude Opus 5.5 (US$ 4/US$ 20 por milhão de tokens, contexto de 1 milhão de tokens, effort definido como medium por padrão), e desde essa versão o Opus também é o modelo inicial de todos os planos. A escolha, portanto, é quando sair dele: continue com o Opus para decisões de arquitetura, depuração difícil, compreensão de sistemas complexos, análise de segurança e trabalho com agentes de longa duração, e mude para /model sonnet quando a tarefa for rotineira o suficiente para que pagar metade do preço por token importe mais que o raciocínio adicional.²²⁰²²¹ (O alias opus apontava para o Opus 5 a US$ 5/US$ 25 da v2.1.219 até a v2.1.278.)¹⁹⁷ O restante deste parágrafo descreve o Opus 4.7 no lançamento em 16 de abril de 2026, mantido como registro histórico.¹⁴⁴¹⁴⁷ O Opus 4.7 resolve 3× mais tarefas de produção no SWE-Bench que o Opus 4.6, alcança 70% no CursorBench (contra 58%) e aumenta a taxa de resolução em 13% em um benchmark interno de programação com 93 tarefas.¹⁴⁴ O Claude Code usa o nível de esforço xhigh por padrão no Opus 4.7, ajustável por /effort (v2.1.111+).¹⁴⁶¹⁴⁷ O modo automático está disponível para assinantes Max no Opus 4.7 pela API da Anthropic sem exigir --enable-auto-mode; nos demais planos/provedores, a disponibilidade depende do plano e dos controles do administrador.¹⁴⁶ Contexto de 1 milhão de tokens pelo preço padrão — sem cobrança adicional por contexto longo. Mudanças de comportamento que você deve conhecer: o Opus 4.7 segue as instruções de forma mais literal, ajusta o tamanho da resposta à complexidade da tarefa, executa menos subagents por padrão e adota um tom mais direto, com menos frases voltadas a validar o que você diz. Se seus prompts contêm instruções auxiliares para forçar mensagens intermediárias de progresso ou verificações adicionais, experimente removê-las.¹⁴⁵

Opusplan: Um modo híbrido que usa o Opus para planejamento (quando a qualidade do raciocínio importa mais) e o Sonnet para execução (quando a velocidade importa). Excelente para refatorações complexas em que você quer o melhor plano, mas não precisa de raciocínio no nível do Opus para cada edição individual.

Como trocar de modelo

Durante a sessão:

> /model opus
> /model sonnet
> /model haiku

Na inicialização:

claude --model opus

Por variável de ambiente:

export ANTHROPIC_MODEL=opus

No settings.json:

{
  "model": "claude-sonnet-5"
}

Personalize o próprio seletor (modelPicker, v2.1.242+): um arquivo de configurações do usuário ou de configurações gerenciadas pode listar os modelos oferecidos por /model, na sua ordem e com seus rótulos, em vez de manter a lista integrada como único menu. Cada entrada especifica um model (qualquer formato aceito por --model, incluindo IDs do Vertex e do Bedrock), com label e description opcionais; defina replaceBuiltInOptions como true para mostrar apenas essas entradas, além de Padrão e do modelo atual da sessão. As configurações do projeto e as locais são ignoradas para essa chave, e uma lista de permissões availableModels continua filtrando as entradas. O Claude Code remove as entradas que não consegue atender, exibe em cinza aquelas que você ainda não pode selecionar, com o motivo, e volta à lista integrada se nenhuma entrada restar.²⁵⁰²⁴⁸

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

Especificamente para subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

A partir da v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL define o modelo padrão dos subagents, em vez de sobrescrever tudo: o model: na definição de um agente e um modelo explícito definido na criação de cada subagent têm precedência sobre essa variável.²⁰⁶ A partir da v2.1.257, CLAUDE_CODE_SUBAGENT_MODEL_FORCE permite reativar o comportamento anterior: aplica CLAUDE_CODE_SUBAGENT_MODEL (ou o modelo da conversa principal quando essa variável não está definida) a todos os subagents, ignorando as escolhas feitas na criação e o model: das definições dos agentes.²¹¹

Cadeia de modelos alternativos (v2.1.166+): a configuração fallbackModel define até três modelos alternativos, testados em ordem quando o modelo principal está sobrecarregado ou indisponível. A flag --fallback-model (antes usada apenas para troca durante a sessão) agora também se aplica a sessões interativas desde a inicialização.²⁶³

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Quando a API retorna um erro inesperado que não permite nova tentativa, o Claude Code agora também tenta executar o turno uma vez no modelo alternativo antes de exibir a falha. Assim, um problema transitório no modelo principal é contornado sem descartar o turno.²⁶³ A partir da v2.1.286, quando a API da Anthropic recusa o modelo para o qual sua configuração padrão ou um alias aponta, o Claude Code tenta novamente uma vez com o modelo anterior da mesma categoria, em vez de falhar em todos os turnos. Novas tentativas por recusa ou por --fallback-model que usam um modelo sem suporte à execução rápida rodam em velocidade padrão.²³¹

A partir da v2.1.178, a compactação também respeita a cadeia de modelos alternativos — se o modelo principal estiver sobrecarregado ou indisponível durante a compactação, essa etapa recorre à cadeia configurada em fallbackModel/--fallback-model, em vez de fazer o turno falhar. Em uma execução autônoma longa, isso elimina a brecha em que uma compactação que poderia ser recuperada acabava encerrando a sessão por um erro transitório do modelo.¹⁷³

Contexto estendido

Para bases de código grandes ou sessões longas, ative o contexto de 1 milhão de tokens:

claude --model sonnet[1m]
claude --model opus[1m]           # 1M for a model that reaches it only through [1m], such as Opus 4.6

Ou, dentro de uma sessão:

> /model sonnet[1m]
> /model opus[1m]

Onde o sufixo faz diferença (outubro de 2026): na API da Anthropic, o Fable 5.1, o Fable 5, o Sonnet 5.5, o Sonnet 5 e o Opus 4.7 e posteriores (incluindo o Opus 5.5) usam a janela de 1 milhão de tokens em todos os planos, então [1m] não muda nada nesse caso. A partir da v2.1.287, o mesmo vale para o Amazon Bedrock, a Agent Platform do Google Cloud, o Microsoft Foundry e o gateway de aplicativos do Claude: o Opus 4.7 e posteriores e o Fable usam a janela de 1 milhão de tokens por padrão, sem o sufixo [1m], e CLAUDE_CODE_DISABLE_1M_CONTEXT=1 os mantém em 200 mil. Antes da v2.1.287, o Opus 4.8 e posteriores usavam 200 mil nesses provedores, a menos que o ID do modelo fixado em ANTHROPIC_DEFAULT_OPUS_MODEL incluísse [1m]; as páginas da documentação do Bedrock e da Agent Platform, consultadas em 1º de outubro, ainda descrevem o sufixo como a forma de obter 1 milhão nesses provedores. O Sonnet 5 tem contexto de 1 milhão de tokens em todos os provedores. O sufixo ainda faz diferença para o Opus 4.6 e o Sonnet 4.6, que só chegam a 1 milhão pela variante [1m].^223232233

O Opus 4.7, o Opus 4.6 e o Sonnet 4.6 incluem a janela de contexto completa de 1 milhão de tokens pelo preço padrão — sem cobrança adicional por contexto longo.¹⁴⁸ Uma solicitação de 900 mil tokens é cobrada pela mesma tarifa por token que uma solicitação de 9 mil tokens. Os descontos de cache de prompts e processamento em lote se aplicam às tarifas padrão em toda a janela de contexto. O acesso às variantes [1m] depende do plano: o Opus 4.6 com contexto de 1M está incluído nos planos Max, Team e Enterprise, e o Sonnet 4.6 com contexto de 1M exige créditos de uso em todos os planos de assinatura, incluindo o Max.²³³ (O Opus com 1M se tornou o padrão nos planos Max, Team e Enterprise na v2.1.75, em 13 de março de 2026.)¹¹⁷¹⁴⁷ Usuários da API e da modalidade de pagamento conforme o uso têm acesso completo a 1M pelas tarifas padrão por token.¹⁴⁷

Para desativar as variantes de contexto de 1M no seletor de modelos, defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1. A partir da v2.1.223, o alcance da variável mudou: ela limita todos os modelos com uma janela nativa de 1M a 200K por meio da compactação automática — não apenas uma lista fixa de variantes conhecidas — e um aviso aparece na inicialização quando a compactação automática não está de fato mantendo a sessão em 200K. Se você definiu essa variável para ter previsibilidade de custos em uma família de modelos, agora ela também limita novos modelos de 1M desde o lançamento, em vez de deixar de valer silenciosamente. A mesma versão faz a compactação automática manter sessões com IDs de modelo não reconhecidos dentro da janela de contexto presumida, em vez de permitir que ultrapassem esse limite; CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 restaura o comportamento anterior para gateways que registram IDs personalizados com janelas reais maiores.²⁰⁰ A partir da v2.1.287, essa variável também é a forma de manter o Opus 4.7 e posteriores e o Fable em 200K no Bedrock, Vertex, Foundry e no gateway de apps da Claude, onde 1M se tornou o padrão.²³²

A partir da v2.1.247, a janela padrão de compactação automática do Sonnet 5 usa todo o seu contexto de 1M: sessões com a janela de 1M agora são compactadas automaticamente em cerca de 967K tokens, em vez de cerca de 934K.²⁴⁵ A v2.1.260 estende a compactação automática próxima ao limite aos demais modelos com contexto de 1M: sessões com Opus e Fable agora também são compactadas pouco antes do limite de 1M de tokens, e a compactação de recuperação em contextos muito grandes não é mais interrompida por tempo limite aos 10 minutos.²¹²

URLs base personalizadas recebem a janela de 1M (v2.1.285). Sessões que usam uma ANTHROPIC_BASE_URL personalizada agora utilizam a janela de contexto de 1M dos modelos que a oferecem (Opus 4.7 e posteriores, Sonnet 5 e posteriores, Fable). Se o seu gateway tem um limite de 200K, execute /autocompact 200k.²²⁹²³³

A partir da v2.1.271, --resume mantém a janela [1m]: retomar uma sessão cuja família de modelos difere do modelo padrão configurado não remove mais o sufixo [1m].²¹⁶

A v2.1.273 corrige a contagem feita pelo medidor de contexto e pela compactação automática, que contabilizavam os turnos da ferramenta advisor como aproximadamente o dobro do tamanho real de contexto – a compactação automática era acionada em cerca de metade da janela real.²¹⁷

Como verificar o modelo atual

> /status

O comando mostra o modelo atual, informações da conta, configurações aplicadas e outros dados do estado da sessão.

Rótulos do seletor de modelos (v2.1.51+): O seletor /model agora mostra rótulos legíveis (por exemplo, “Sonnet 4.6”) em vez dos IDs brutos dos modelos para versões fixadas, com indicações de atualização quando há versões mais recentes disponíveis.⁹⁸ A v2.1.219 corrige a linha unificada do Opus, que aparecia apenas como “Opus” em vez de “Opus (contexto de 1M)”, e restringe o destaque de novo lançamento ao nome do modelo mais recente, para que ele marque o que de fato foi lançado, em vez de um trecho arbitrário da lista.¹⁹⁶ A v2.1.283 remove “(contexto de 1M)” da linha do Opus e do nome do modelo padrão nos casos em que o Opus já tem uma janela de contexto de 1M; a janela em si permanece igual.²²⁶

Modo rápido (v2.1.36+)

O modo rápido oferece uma geração de saída significativamente mais rápida com o mesmo modelo; ele não troca para um modelo mais barato. Ative ou desative esse modo durante uma sessão com /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Quais modelos (a partir da v2.1.280): o modo rápido se aplica ao Claude Opus 5.5, Opus 5 e Opus 4.8, e o Opus 5.5 é o padrão do modo rápido desde a v2.1.280 (o Opus 5 era o padrão desde a v2.1.219). A v2.1.219 removeu o Opus 4.7 do modo rápido, e o recurso nunca esteve disponível no Sonnet, Haiku ou Fable. Ele continua sendo uma prévia de pesquisa disponível apenas na API da Claude (incluindo Claude Managed Agents) — não no Amazon Bedrock, Google Cloud, Microsoft Foundry ou Claude Platform on AWS. O acesso é restrito: entre em contato com o gerente da sua conta ou entre na lista de espera.^196198223

Sessões remotas (v2.1.271): o modo rápido agora está disponível nas sessões do Claude Code Remote – sessões na nuvem e runners em infraestrutura própria. A configuração de modo rápido do host é aplicada, ou você pode digitar /fast na própria sessão; as duas opções só funcionam quando a sua organização permite o modo rápido. A mesma versão corrige /fast off: agora ele desativa o modo rápido em vez de responder “Modo rápido indisponível” quando a organização está com o modo rápido desativado.²¹⁶

Preços (modo rápido):^198222223

A armadilha do Opus 4.7 (v2.1.219). Modelos sem suporte não se comportam da mesma maneira. Uma requisição para claude-opus-4-7 com speed: "fast" agora retorna um erro — ela não passa silenciosamente para a velocidade padrão. O Opus 4.6 é a exceção que torna esse detalhe relevante: ele aceita speed: "fast", executa na velocidade padrão mesmo assim, cobra as tarifas padrão e informa usage.speed: "standard". Se o seu harness estava fixado na versão 4.7 e dependia de as requisições em modo rápido passarem silenciosamente para a velocidade padrão, agora elas falham; altere a versão fixada para Opus 5.5, Opus 5 ou Opus 4.8.¹⁹⁸

Quando usar o modo rápido: - Ao iterar rapidamente em pequenas alterações quando a latência é o gargalo - Ao gerar testes, código boilerplate ou código repetitivo quando a velocidade importa mais que o custo - Ao executar uma lista de tarefas semelhantes em sequência

Quando NÃO usar o modo rápido: - Tarefas de longa duração executadas por agentes (o custo continua dobrado durante toda a execução) - Trabalho de subagents em segundo plano (ninguém está esperando pela saída) - Sessões com orçamento limitado

O modo rápido inclui a janela de contexto completa de 1M (v2.1.50+). O preço usa um multiplicador fixo em todo o contexto, incluindo requisições com mais de 200K tokens de entrada — sem cobrança adicional por contexto longo —, e esse multiplicador se acumula com os de cache de prompts e residência de dados.⁹⁶¹⁹⁸

Notas operacionais. O modo rápido tem seu próprio limite de taxa, separado dos limites padrão do Opus; excedê-lo retorna um 429 com retry-after (os cabeçalhos de resposta anthropic-fast-*-tokens-* informam a capacidade restante). Alternar entre os modos rápido e padrão invalida o cache de prompts — requisições em velocidades diferentes não compartilham prefixos em cache, então alternar /fast no meio da sessão custa uma requisição sem aproveitamento do cache. O modo rápido não está disponível com a Batch API nem com um compromisso de uso do Priority Tier.¹⁹⁸

Dica de especialista: O modo rápido não combina com opusplan (o opusplan já mistura Opus e Sonnet; o modo rápido afeta apenas a etapa com Opus). Use-o quando a latência importar mais que o custo e desative-o para trabalhos autônomos ou em lote. /fast exige uso extra; administradores de Team/Enterprise podem precisar habilitá-lo primeiro (correção da v2.1.37). Desative-o por completo com CLAUDE_CODE_DISABLE_FAST_MODE=1. A partir da v2.1.218, o Claude Code avisa quando uma troca de modelo via /config model=<x> ou Remote Control altera o estado do modo rápido, e a v2.1.219 corrigiu os clientes do Remote Control que mantinham um status desatualizado do modo rápido após uma troca, reconexão ou falha na verificação da organização.^86149195196

A ferramenta advisor (experimental)

A ferramenta advisor permite que o Claude consulte um segundo modelo, geralmente mais capaz, em momentos-chave de uma tarefa: antes de decidir por uma abordagem, quando um erro continua se repetindo ou antes de declarar o trabalho concluído. O advisor é executado no servidor, na infraestrutura da Anthropic, como uma ferramenta de servidor, recebe a conversa completa, incluindo todas as chamadas de ferramentas e seus resultados, e retorna orientações que o Claude aplica antes de continuar. O Claude decide quando chamá-lo; você pode pedir uma consulta em um prompt, e não há configuração que limite ou force as chamadas. O recurso é experimental, está disponível na API da Anthropic para contas com assinatura e contas com cobrança pela API, e chegou à Claude Platform on AWS na v2.1.300 (a página da documentação ainda lista essa plataforma como não compatível). Ao passar por um gateway, o recurso depende de a requisição chegar intacta à API da Anthropic e precisa buscar as flags de recursos, por isso uma variável como DISABLE_TELEMETRY o mantém desativado.²⁷³²⁷⁴ Como ativar. Há três formas: /advisor <model> durante a sessão, que salva a escolha em advisorModel nas suas configurações de usuário (usar apenas /advisor abre um seletor no terminal e exibe o advisor atual em sessões -p, SDK, desktop e Remote Control, nas quais a forma textual funciona desde a v2.1.260; /advisor off desativa o recurso); "advisorModel": "opus" em um arquivo de configurações; ou claude --advisor <model> para uma única sessão, uma flag que não aparece em --help, tem prioridade sobre a configuração e encerra a execução na inicialização se a combinação for inválida. Os aliases são fable, opus e sonnet, ou você pode usar um ID de modelo completo. CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 remove o comando, ignora a configuração e faz a flag não ter efeito.²⁷⁴

Combinações, custo e o que você vê. Um advisor precisa ter classificação igual ou superior à do modelo principal: Opus 4.7 e 4.8 aceitam Fable, Opus 4.7 ou posterior e Sonnet 5.5 (desde a v2.1.287); Sonnet 5.5 aceita Fable, Opus 5 ou posterior e Sonnet 5.5; Opus 5 e 5.5 aceitam Fable e Opus 5 ou posterior; Fable 5.1 aceita apenas Fable 5.1; Haiku 4.5 pode consultar o advisor, mas não pode atuar como um. Um advisor com classificação inferior à do modelo principal não é vinculado, e uma notificação informa isso; um advisor recusado pela API é descartado silenciosamente pelo restante da conversa. Os subagents herdam o advisor, sujeito à mesma verificação de combinação, e a lista de modelos permitidos em availableModels é respeitada. Cada chamada é cobrada pelas tarifas de entrada e saída do modelo advisor ou conta para os limites do plano, com uma exceção: um advisor Fable consome créditos de uso nos planos em que o Fable é cobrado assim, após o consentimento único dado por meio de /model fable. Ativar ou desativar o advisor preserva o cache de prompt do modelo principal; a leitura da conversa feita pelo próprio advisor nunca é armazenada em cache. No registro da conversa, uma linha Advising informa Revisado, Recusado ou Indisponível, e Ctrl+O mostra as orientações. Os mods veem as chamadas ao advisor como serverToolUses em turn.step (v2.1.290).²⁷⁴

Controle de esforço (v2.1.111+, Opus 4.7)

O Opus 4.7 introduz um novo controle de esforço que ajusta o equilíbrio entre velocidade e inteligência. Use /effort durante uma sessão:

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Salvo por modelo (v2.1.251+): /effort agora salva seu nível de esforço padrão por modelo, para que cada modelo mantenha sua própria configuração quando você alterna entre eles – o hábito de usar xhigh no Opus não acompanha mais você ao mudar para o Haiku (CHANGELOG: “Alterado /effort para salvar seu nível de esforço padrão por modelo, para que cada modelo mantenha sua própria configuração quando você alterna entre eles”). A exceção que limita max à sessão atual continua valendo.²⁰⁶ Teclas do controle deslizante na v2.1.284: as ações de atalhos de teclado effortSlider:decreaseEffort, increaseEffort e toggleUltracode permitem reatribuir as teclas de seta e Tab do controle deslizante em keybindings.json.²²⁸ A v2.1.257 refina os dois controles: /effort aceita s para uma escolha válida apenas na sessão, seguindo a convenção de /model, e a flag --effort agora se limita à sessão – ela libera a restrição ao esforço padrão de um novo modelo apenas naquela sessão, em vez de permanentemente (a referência da CLI diz que ela “Substitui” o padrão “nesta sessão e não persiste”).²¹¹²⁴³

Modo automático no Max (v2.1.111+)

O modo automático é o modo de permissão inicial integrado para sessões interativas no terminal e no VS Code em todos os planos e provedores (v2.1.283-284) e, da v2.1.285 até a v2.1.302 reverter a mudança, também para sessões claude -p e Python Agent SDK em provedores de terceiros ou com a telemetria desativada; ele já era o padrão no Pro, Max e Team desde 14 de agosto de 2026 (anunciado em 7 de agosto). Consulte Modos de permissão para ver os números do estudo apresentado no anúncio, as formas de desativar esse padrão e as sessões que ainda iniciam no modo manual.^{203226227228229}

Um modelo classificador separado, Claude Sonnet 5 desde a v2.1.210, analisa cada ação antes da execução, verificando se ela corresponde à sua intenção e é segura.¹⁸⁷ Inicie uma sessão no modo automático com --permission-mode auto; a v2.1.111 removeu a antiga flag --enable-auto-mode.

Como a disponibilidade foi ampliada:

• Desativação: CLAUDE_CODE_AUTO_MODE_SERVER=0 mantém o classificador local, cujas solicitações contam para o uso, e 1 ativa as verificações do servidor. Antes da v2.1.281, a variável não era lida em uma conexão direta com Anthropic API; a v2.1.281 passou a aplicá-la também nesse caso, e a documentação de cobrança do modo automático agora informa que, em uma conexão direta, ela exige a v2.1.281 ou posterior.²²⁴²²⁷ A documentação descreve a variável como temporária. Definir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 enquanto a variável não está definida também interrompe as verificações do servidor.
• Quando as verificações do servidor não conseguem alcançar uma sessão: a causa mais comum é um gateway ou proxy que remove o campo safeguards das solicitações, exclui safeguard_results das respostas ou reescreve os IDs de uso de ferramentas. O Claude Code exibe um aviso uma única vez (“esta sessão não é elegível”), informa o nome do gateway quando consegue identificá-lo e usa suas próprias solicitações cobradas ao classificador pelo restante da sessão. No modo -p, o aviso vai para stderr, e a saída stream-json emite um aviso system. Sessões Pro, Max e Team nunca recebem esse aviso. A correção no gateway é repassar os campos das solicitações e as chaves das respostas sem alterações.
• Verificação de uma sessão: /status mostra uma linha Servidor do modo automático com o valor Enabled enquanto as verificações do servidor decidem as ações da sessão e Disabled após a mudança para o classificador local.²¹⁹

O que o modo automático não é: uma barreira de segurança. A maior parte do que vem a seguir reforça um classificador, e um classificador não é uma sandbox. Em 26 de agosto de 2026, o pesquisador de injeção de prompt Johann Rehberger publicou uma cadeia de ataque funcional contra o Claude Code Opus 5 no modo automático, relatando uma taxa de sucesso de 60–80% em amostras pequenas — 3 de 5 execuções para a cadeia principal, que inicia um processo filho isolado de python3, e 3 de 5 e 4 de 5 execuções para duas configurações de uma variante cuja carga maliciosa inicia uma instância de claude -p sem interface — com a ressalva, feita por ele mesmo, de que são amostras pequenas, e não uma medição universal da taxa de sucesso do ataque.²¹⁰ Vale entender essa cadeia porque cada etapa, isoladamente, parece razoável: um servidor responde ao WebFetch com HTTP 415, levando o agente a recorrer ao curl; o arquivo compactado baixado é extraído em um diretório temporário contendo um manifesto, sete registros de dados codificados com Base85/zlib, um binário nativo e um struct.py; o Claude se recusa a executar o binário não confiável e então escreve seu próprio decodificador em Python e o executa dentro desse diretório; o decodificador importa base64, base64 importa struct, e o Python encontra primeiro o struct.py do invasor. Nada na sequência é uma instrução obviamente maliciosa — a injeção só precisa fazer o caminho comprometido parecer a maneira mais razoável de concluir a tarefa. Rehberger também relata que, em algumas execuções, o Claude tentou encerrar o processo do malware ao perceber o comprometimento, e o modo automático negou o comando de limpeza.²¹⁰ Ele contrapõe a descoberta a um número que a Anthropic divulgou: uma avaliação encomendada a terceiros relatou uma taxa de sucesso de 0,00% para ataques de injeção de prompt contra o Opus 5 no modo automático, em 72 cenários executados dez vezes cada. A cadeia dele não fazia parte desse conjunto, o que explica como um resultado de 0,00% no benchmark e uma cadeia funcional de execução de código podem ser verdadeiros ao mesmo tempo; para ele, as duas mensagens não se encaixam.²¹⁰ Observe também a classificação: a atualização de Simon Willison de 30 de agosto endossa a observação de um leitor de que esse não é um caso clássico de injeção de prompt — o modelo nunca lê nem segue instruções do invasor —, mas um ataque de confusão de ambiente.²¹⁰

A Anthropic encerrou o relato como Informativo — o comportamento estava funcionando conforme projetado —, e a posição relatada por Rehberger é a que deve orientar o projeto: o modo automático é um classificador que faz o melhor possível, e não uma garantia de segurança; cadeias de injeção elaboradas com persistência a partir de etapas individualmente benignas estão fora do que se espera que um classificador detecte; e a verdadeira barreira de contenção é o isolamento no nível do sistema operacional e o controle do tráfego de saída da rede.²¹⁰ Isso não contradiz as medidas de reforço abaixo — é a perspectiva correta para entendê-las. O modo automático reduz o número de solicitações de confirmação às quais você precisa responder e bloqueia uma lista documentada de operações destrutivas; ele não torna segura uma sessão com entradas não confiáveis. Se uma sessão tiver contato com conteúdo sob influência de um invasor — páginas acessadas, arquivos compactados baixados, textos de issues, servidores MCP de terceiros —, os controles que realmente limitam os danos são os externos ao modelo: um contêiner ou uma VM, restrições ao tráfego de saída da rede, monitoramento do que o agente realmente faz e um diretório pessoal que não contenha as chaves SSH e as credenciais de nuvem que você não gostaria de perder. A aprovação pelo modo automático não é evidência de que uma ação era segura.

Regras personalizadas sem perder as padrão (v2.1.118+). Nas versões anteriores, autoMode.allow, autoMode.soft_deny e autoMode.environment exigiam uma escolha: definir sua própria lista significava perder as regras de segurança integradas. O marcador $defaults resolve isso — ele é expandido para a lista integrada exatamente na posição em que você o coloca, permitindo acrescentar regras personalizadas antes e depois dela:¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

Edite as regras do classificador pelo /permissions (v2.1.246). Execute /permissions e abra a aba Modo automático, que aparece apenas quando o modo automático está disponível para a sessão. Ela lista as entradas de allow, soft_deny, hard_deny e environment de todos os escopos lidos pelo classificador e mostra se as regras integradas estão em vigor em cada seção; entradas de configurações gerenciadas ou de --settings são somente leitura, e cada alteração é salva em ~/.claude/settings.json. Adicionar a primeira regra a uma seção também insere "$defaults" para manter as regras integradas em vigor; você pode ativar ou desativar as regras integradas por seção (uma seção precisa ter pelo menos uma regra sua para que as integradas possam ser desativadas), e environment é aberto como um único documento no seu editor.²⁴⁹²⁴⁷

Opção “Não perguntar novamente” na ativação (v2.1.118+). A solicitação de ativação do modo automático agora oferece a opção “Não perguntar novamente”, para que usuários frequentes possam ocultar a explicação sem precisar automatizar o uso de uma flag.¹⁵²

Proteções contra comandos destrutivos (v2.1.183). O modo automático agora bloqueia de forma obrigatória um conjunto de comandos irreversíveis, a menos que você os tenha solicitado explicitamente na sessão: operações destrutivas do git (git reset --hard, git checkout -- ., git clean -fd, git stash drop) quando você não pediu para descartar o trabalho local; git commit --amend quando o commit não foi feito pelo agente na sessão atual; e a destruição de infraestrutura (terraform destroy, pulumi destroy, cdk destroy), a menos que você tenha indicado a stack específica. Isso limita o alcance dos danos causados pelo classificador justamente nas operações que perdem trabalho silenciosamente ou destroem ambientes — o agente ainda pode executá-las, mas apenas por instrução explícita sua, nunca por iniciativa própria.¹⁷⁴

Classifique todos os comandos de shell (v2.1.193). Por padrão, o classificador do modo automático só analisa comandos de shell que correspondem a padrões de execução de código arbitrário; comandos rotineiros não passam por ele. A nova configuração autoMode.classifyAllShell encaminha todos os comandos Bash/PowerShell ao classificador, trocando um pouco de latência por uma proteção mais rigorosa quando você quer que cada chamada de shell seja avaliada. A mesma versão também exibe os motivos das recusas do modo automático no registro da sessão, na notificação de recusa e nas recusas recentes de /permissions, para que o bloqueio de um comando venha acompanhado de uma explicação.¹⁷⁹

Mais três regras de reforço (v2.1.205). O modo automático agora bloqueia a adulteração dos arquivos de registro da sessão — a própria trilha de auditoria fica fora do alcance do agente; pede confirmação antes de executar rm -rf sobre uma variável cujo valor não consegue determinar pelo contexto — evitando acidentes do tipo rm -rf $DIR com $DIR desconhecido; e as notificações de tarefas em segundo plano agora declaram explicitamente que não houve nenhuma intervenção humana, para que uma linha inventada de “o usuário aprovou” dentro de um registro não possa ser tratada como uma aprovação válida e executada.¹⁸³ A terceira regra é uma defesa contra injeção de prompt que vale assimilar: a aprovação precisa chegar pelo canal de aprovação, e o harness agora torna essa premissa explícita. A substituição de comandos não consegue esconder uma catástrofe (v2.1.208). Remoções catastróficas como rm -rf ~ agora pedem confirmação mesmo quando estão escondidas em $(...), crases ou substituição de processo (<(...)) — e a confirmação aparece até com --dangerously-skip-permissions e no modo automático. Encapsular um comando destrutivo em uma substituição não permite mais que ele passe despercebido pela proteção.¹⁸⁶

Redefina o estado do modo automático: claude auto-mode reset (v2.1.212). Um novo subcomando redefine o estado do modo automático pelo terminal; passe --yes para pular a confirmação:¹⁸⁹

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

Menos caixas de diálogo, o mesmo rigor (v2.1.218). Três verificações que antes interrompiam o modo automático com uma caixa de diálogo de permissão — rm perigoso, & em segundo plano e caminhos suspeitos do Windows — deixaram de fazer isso; agora o classificador do modo automático decide sobre elas, então a análise de segurança continua acontecendo sem exigir sua intervenção a cada ocorrência. A mesma versão estende esse comportamento ao modo de planejamento com modo automático: comandos Bash que o analisador estático não consegue comprovar que são somente de leitura deixam de pedir confirmação — o classificador os avalia em vez de recorrer a uma caixa de diálogo.¹⁹⁵

Regra de escape de contenção (v2.1.257). A lista do classificador de ações que nunca devem ser aprovadas automaticamente ganha a regra “Containment Escape”: buscas de credenciais em metadados de nuvem, evasão de controles de tráfego de saída e acesso entre tenants deixam de ser aprovados automaticamente, a menos que o ambiente os marque como esperados. Entenda isso no contexto da ressalva acima: um reforço contínuo do classificador – mais uma categoria documentada de bloqueio, sem mudar o que é o modo automático.²¹¹

Confirmação única para leituras fora dos diretórios de trabalho (v2.1.257). O modo automático agora pede confirmação uma vez, antes da primeira leitura de arquivo da sessão fora dos diretórios de trabalho; desde a v2.1.284, essa confirmação também oferece a opção Sim, mas pergunte novamente na próxima vez.²²⁸ A configuração complementar permissions.blockReadsOutsideWorkingDirectories transforma a confirmação em uma recusa – essas leituras são bloqueadas diretamente.²¹¹ A v2.1.273 estende os dois comportamentos ao que o verificador não consegue enxergar: um comando Bash que ele não consegue analisar por completo pede confirmação em vez de pular a verificação, e um diretório de memória escolhido pelas configurações de um repositório deixa de ser carregado no prompt, consultado, indexado ou usado pela extração de memória quando a configuração de bloqueio está ativa.²¹⁷

URLs de renderizadores de diagramas contam como uploads (v2.1.261). Um link que embute conteúdo na URL de um renderizador público de diagramas – no estilo mermaid.live, com os dados codificados na própria URL – deixa de ser aprovado automaticamente, a menos que você tenha solicitado isso. O classificador trata esse link como um upload: os dados embutidos viajam na própria URL, onde os scripts do site do renderizador podem lê-los assim que a página abre – links no estilo mermaid.live carregam os dados no fragmento da URL, que o navegador entrega ao JavaScript da página em vez de enviá-los na requisição de rede. Vale o mesmo contexto da ressalva acima: mais um canal de exfiltração fechado no reforço do classificador, sem estabelecer um novo limite.²¹⁴

Os dois modos de falha do classificador ganham condições de parada (v2.1.280). Até esta versão, o modo automático não sabia como lidar com uma verificação de segurança que não retornasse um parecer utilizável, e as duas lacunas se manifestavam da mesma forma para quem operava: um turno que ficava em loop, consumindo tokens em uma ação que nunca seria aprovada. A v2.1.280 dá a cada caso um estado final.

A análise no servidor abrange mais comandos (v2.1.281). Quando a análise do classificador acontece no servidor, comandos de shell somente de leitura e executados em sandbox agora também aguardam essa análise e são bloqueados quando ela os sinaliza. A mensagem de recusa também mudou, para que Claude entenda que a recusa abrange o resultado, não apenas o comando exato. Depois que uma sessão é retomada em um novo processo, o classificador pode reutilizar seu cache de prompt anterior em vez de reescrevê-lo. E /insights ganha uma recomendação de modo automático que estima quantas solicitações de permissão esse modo poderia ter resolvido nas suas sessões recentes.²²⁴

Sessões sem supervisão deixam de ficar esperando confirmações de rm (v2.1.281). No modo automático e com --dangerously-skip-permissions, a confirmação de rm perigoso agora espera 2 minutos por uma resposta e depois nega o comando com uma sugestão de reescrita, permitindo que uma sessão sem supervisão continue; CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1 desativa esse tempo limite. Um rm recursivo cujo alvo é apenas a saída de uma substituição de comando, como rm -rf "$(pwd)", antes era executado sem confirmação nos dois modos; agora ele pede confirmação mesmo quando corresponde a uma regra de permissão do Bash, a menos que CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1 esteja definido. A verificação de rm perigoso também sinaliza remoções cujo alvo é uma variável de shell seguida pelo nome de um diretório de nível superior, uma variável derivada do diretório de trabalho ou um alvo composto apenas por barras invertidas.²²⁴ Desde a v2.1.299, um script de shell -c que não executa rm deixa de pedir confirmação, e um rm construído em tempo de execução dentro de um script que Claude Code não consegue ler só pede confirmação quando CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1 está definido.²⁷¹

Comandos de shell inline com ! saem do classificador; retornos de subagents entram (v2.1.271). São duas mudanças de funcionamento, sem novas categorias de bloqueio. Os comandos de shell inline com ! de uma skill ou de um comando de barra agora seguem as regras de permissão do modo padrão em vez do classificador – um comando sobre o qual nenhuma regra decide é executado como uma chamada de ferramenta submetida à análise. E um subagent agora devolve seu resultado a quem o chamou por meio de uma chamada de retorno dedicada, analisada pelo classificador de segurança, em vez de ter sua última mensagem analisada posteriormente – o ponto de verificação passou de depois da entrega para o próprio momento da entrega.²¹⁶

Novidades nas versões v2.1.309 e v2.1.310

Claude Code 2.1.309 foi lançado em 22 de outubro de 2026 (npm às 20:34 UTC; lançamento no GitHub às 22:18 UTC, 79 itens) e a versão 2.1.310 em 23 de outubro (npm às 21:20 UTC; lançamento no GitHub às 23:39 UTC, 26 itens), ambos idênticos ao CHANGELOG canônico. As tags latest e next do npm apontam para a versão 2.1.310, e stable passou da 2.1.292 para a 2.1.308, uma versão cuja nota completa diz “Correções de bugs e melhorias de confiabilidade”; a versão 2.1.303 (18 de outubro) traz a mesma linha. Nenhuma versão foi pulada entre a 2.1.302 e a 2.1.310.²⁷⁸

Correções de sandbox e permissões (v2.1.309). Comandos Bash executados em sandbox no macOS e no Linux deixam de executar os arquivos de inicialização do shell fora do sandbox antes de cada comando; no macOS, os padrões glob de denyWrite são aplicados à localização real de um caminho quando a pasta do padrão é acessada por um link simbólico; comandos executados em sandbox e edições aceitas automaticamente não podem mais modificar o arquivo de configuração de MCP passado com --mcp-config; no Linux, bloqueios de escrita deixam de ser suspensos quando um comando em segundo plano continua ativo após o fim da sessão; e comandos que as configurações excluem do sandbox agora pedem confirmação antes de escrever nos caminhos da lista de escrita permitida quando o sandbox está habilitado, mas não consegue funcionar, com a alternativa de execução fora do sandbox recusada nesse caso. As verificações de permissão do Bash deixam de confiar em uma variável definida por um comando cujo redirecionamento pode falhar, pedem confirmação para um cd encapsulado ou com prefixo antes de git e aplicam uma regra de bloqueio Edit(path) a um redirecionamento Bash dentro de um subshell; a proteção de isolamento de worktree recusa mais comandos com prefixos de locale e comandos aritméticos do zsh; a proteção contra escrita no armazenamento de perfis também se aplica quando o diretório de configuração é acessado por um link simbólico. sed -i agora recebe a solicitação de permissão padrão do Bash e é executado como foi escrito, em vez de exibir uma prévia simulada de edição de arquivo, e, assim como outras edições pelo Bash, deixa de ser revertido por /rewind. Veja Modo sandbox.²⁷⁸ Confiança, worktrees e skills (v2.1.309). claude ultrareview exige que você confirme a confiança no espaço de trabalho: solicita essa confirmação em um terminal e se recusa a executar caso contrário; scripts passam --trust-workspace, que não recebe valor, ou definem CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1. No modo que ignora permissões no aplicativo desktop e no VS Code, a confirmação para comandos perigosos com rm e rmdir agora nega o comando imediatamente e sugere uma reformulação, permitindo que sessões sem supervisão continuem. A criação e a reutilização de worktrees não buscam mais objetos do git sob demanda (um clone parcial com sandbox do Bash os busca primeiro), e worktrees e checkouts de branches ignoram as referências de substituição do git. Um CLAUDE.md aninhado que excede o limite de tamanho agora carrega apenas o início, evitando compactações repetidas da sessão após a leitura de arquivos sob seu escopo. Uma skill em uma pasta de --add-dir cujo nome já pertence a outra skill é disponibilizada como <folder>:<name>, e /verify e /code-review encontram a skill própria de um pacote aninhado. Agentes da equipe em painéis divididos herdam as regras de negação de ferramentas e de --tools do líder, e /rewind lista os turnos que alteraram arquivos com checkpoints por meio de /code-review --fix, de um subagent ou de um comando do shell.²⁷⁸

v2.1.310. A ferramenta Monitor e os monitores de plugins funcionam no Bedrock, Vertex e Foundry e quando a telemetria ou o tráfego não essencial estão desativados; nesses casos, esperas longas em primeiro plano agora também são bloqueadas. Requisições feitas por meio de gateways e servidores compatíveis que rejeitam o valor beta effort-2025-11-24 ou mensagens de sistema no meio da conversa são reenviadas sem esses elementos. A compactação após um erro “Prompt longo demais” não preserva mais texto denso em excesso, como base64 ou SVG; a limpeza em segundo plano não exclui mais arquivos recentes, como imagens coladas, quando cleanupPeriodDays é muito grande; as solicitações de permissão para leitura de arquivos mostram o destino de links simbólicos; a solicitação do modo automático antes da primeira leitura fora dos diretórios de trabalho informa quando bloquear essas leituras faz com que comandos do shell peçam permissão; sessões não interativas usam menos memória ao compactar um histórico muito grande; no Ubuntu, /sandbox e o aviso de inicialização identificam a restrição do AppArmor sobre namespaces de usuário e explicam como removê-la; o Image de um mod é renderizado dentro do tmux com allow-passthrough e focus-events ativados, e no kitty, Ghostty e iTerm2 3.5+ com renderização em tela cheia; e uma chamada de ferramenta MCP que excede o tempo limite em uma sessão não interativa enquanto a solicitação de informações do servidor continua sem resposta orienta Claude a não repeti-la. As permissões de sessões na nuvem e do Remote Control passam a integrar os papéis personalizados do Enterprise.²⁷⁸

Novidades da v2.1.307

Claude Code 2.1.307 foi lançado em 21 de outubro de 2026 (npm às 20:47 UTC; lançamento no GitHub às 22:17 UTC; 43 itens, idênticos aos do CHANGELOG canônico), após a versão 2.1.306 (21 de outubro, às 02:28 UTC), cujas duas correções fazem com que claude -p dentro de sessões na nuvem não informe mais “Login não realizado” na ausência das variáveis de ambiente da sessão, e que um erro de API não seja mais substituído por “prompt longo demais” seguido de uma compactação desnecessária em sessões com muitas ferramentas MCP. A versão 2.1.308 (22 de outubro, às 04:19 UTC) é o lançamento de confiabilidade com uma única linha de descrição que passou a ser stable.²⁷⁸

Telemetria e a skill de API. O evento OpenTelemetry claude_code.safety_event é emitido para cada chamada de ferramenta que uma regra de permissão, o modo automático, uma verificação de segurança, um hook ou o sandbox bloqueou, submeteu à confirmação ou devolveu (veja a Referência de variáveis de ambiente). /claude-api api-version migra o código de API de Claude para a versão 2026-10-21 de API, e /claude-api managed-agents-secure (v2.1.304) compara as configurações de um agente do Managed Agents com o guia de segurança publicado por Anthropic, sem alterar nada; a skill agora cria equipes de subagents do Managed Agents em multiagent_20261001, com fluxos de trabalho dinâmicos ativados por padrão (v2.1.309).²⁷⁸²⁷⁹

Correções e comportamento. CLAUDE_CODE_DISABLE_1M_CONTEXT com um alias que contém o sufixo [1m], como opus[1m], não produz mais um erro de modelo não encontrado; o cabeçalho beta prompt-caching-scope não é mais enviado por meio de gateways personalizados de ANTHROPIC_BASE_URL nem no Foundry; servidores MCP que não podiam ser acessados enquanto o chaveiro de login do macOS estava bloqueado agora informam o motivo, e a execução seguinte ao desbloqueio se conecta sem exigir um novo login; chamadas HTTP de ferramentas MCP não são mais enviadas duas vezes quando a conexão é encerrada durante a chamada, pois apenas ferramentas somente de leitura ou idempotentes têm novas tentativas; foram corrigidos os erros “A compactação automática está se repetindo excessivamente” em turnos que leem muitas páginas de PDF ou imagens; chamadas de ferramentas que não podem ser interpretadas são repetidas até duas vezes antes de o turno terminar com erro; subagents iniciados juntos por fork recebem, cada um, a indicação de qual inicialização é a sua; /permissions > Negados recentemente mostra o comando do shell negado; a configuração axScreenReader e CLAUDE_AX_SCREEN_READER em um bloco env de configurações só se aplicam quando vêm de configurações do usuário, gerenciadas ou de --settings (desde a versão 2.1.305); e hooks de checkout de runners auto-hospedados são interrompidos após 30 minutos por padrão (--checkout-hook-timeout-min, 0 para não impor limite). O Code Review ganha @claude review stop (também off e pause) para encerrar uma assinatura de @claude review always.²⁷⁸

Novidades das versões v2.1.304 e v2.1.305

Claude Code 2.1.304 foi lançado em 19 de outubro de 2026 (npm às 19:47 UTC; lançamento no GitHub às 21:34 UTC; 76 itens) e a versão 2.1.305 em 20 de outubro (npm às 19:29 UTC; lançamento no GitHub às 20:46 UTC; 38 itens), ambos idênticos ao CHANGELOG canônico; a versão 2.1.303 (18 de outubro) é um lançamento de confiabilidade com uma única linha de descrição.²⁷⁸

Configuração do modo automático e correções de /usage. /auto-mode-setup (v2.1.304) oferece uma configuração guiada que lê seu projeto e suas sessões recentes para propor entradas de autoMode.environment, também disponível no Bedrock, Vertex, Foundry, no gateway de aplicativos de Claude e em sessões com telemetria desativada; a documentação de configuração do modo automático aborda esse recurso. /usage (v2.1.305) transforma cada aviso em uma correção de uma linha que identifica sua origem, e f aplica as correções, que também aparecem no VS Code e em /doctor; /usage também informa quando termina um limite de taxa de acesso aos dados de uso. Nos planos Pro e Max, retomar uma conversa inativa que consumiria uma parcela considerável do limite de uso de 5 horas agora exibe um aviso com a opção de iniciar uma nova conversa (v2.1.304). Veja Modo automático no Max e a linha de /usage em Comandos de barra.²⁷⁸²⁷⁹

Configurações e ambiente. sandbox.allowNestedUserNamespaces (v2.1.305) permite que comandos executados no sandbox no Linux criem namespaces de usuário (Chromium, podman sem root), mas também permite que contornem as proteções de arquivos do sandbox. CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS (v2.1.305) faz o modo de novas tentativas sem supervisão detectar quando um limite de uso é removido antes da redefinição prevista. CLAUDE_CODE_AUTO_COMPACT_WINDOW aceita os sufixos k e M, assim como --autocompact, e avisa sobre valores fora do intervalo (200k antes definia silenciosamente uma janela de 100 mil). allowedMcpServers deixa de filtrar servidores stdio de managed-mcp.json que usam ${VAR} apenas em env, então um servidor que sua lista de permissões não incluía passa a ser carregado após a atualização (use deniedMcpServers para mantê-lo desativado). A busca de ferramentas fica ativada por padrão ao usar um ANTHROPIC_BASE_URL personalizado (v2.1.304), e a v2.1.305 corrigiu a regressão da 2.1.304 que fazia todas as requisições falharem no Vertex, Bedrock e em outros provedores cujos endpoints rejeitam a busca de ferramentas: Claude Code agora tenta novamente sem ela. Plugins que o Claude Desktop monta por caminho perdem seu allowed-tools sob allowManagedPermissionRulesOnly. Todos esses comportamentos constam na documentação em 23 de outubro, exceto a ativação padrão da busca de ferramentas.²⁷⁸²⁷⁹

Mods, skills e hooks. O evento tool.check de um mod inclui e.isReadOnly, sua resposta pode definir decider: "person" para que apenas a caixa de diálogo de permissão ou um callback do host possa aprovar, hooks de settings.read recebem cada camada de configurações e reescrevem as configurações combinadas, uma linha do histórico identifica o plugin que ignorou um dos seus hooks, e um painel acoplado ocupa no máximo 45% da largura do terminal (v2.1.305). Após a compactação, a lista de skills é enviada novamente a Claude, e /reload-skills envia apenas skills novas ou alteradas; as skills de uma mesma origem podem registrar no máximo 1.024 hooks e 16.384 caracteres em padrões de correspondência por sessão; o hook once de uma skill não remove mais o hook idêntico de outra skill. A retomada de fluxos de trabalho recupera os agentes de pipeline() e parallel() já concluídos do registro da execução, em vez de executá-los novamente (v2.1.305); as reativações de /loop com intervalo definido pelo próprio agente, no limite máximo de 1 hora, não ocorrem mais logo após a expiração do cache de prompts; claude --worktree não remove mais o worktree e sua branch sem perguntar ao sair quando HEAD estava desvinculado ou em outra branch; rm -r de uma unidade montada ou de uma pasta em seu nível superior aciona a confirmação de segurança; e o Code Review ganha níveis de revisão (Rápida, Padrão, Profunda) e uma opção para revisar todos os repositórios de uma organização do GitHub. A caixa de diálogo de /fast remove o rótulo “(prévia de pesquisa)” no Opus 5.5.²⁷⁸

Novidades da v2.1.302

Claude Code 2.1.302 foi lançado em 16 de outubro de 2026: o npm publicou a versão às 16:48 UTC, o lançamento no GitHub veio às 20:53 UTC com os mesmos 63 itens do CHANGELOG canônico, e tanto latest quanto next no npm apontam para ela, enquanto stable permanece na 2.1.292. Ela vem depois da 2.1.301 (15 de outubro, 51 itens); nenhuma versão foi pulada. A documentação, consultada em 17 de outubro, já inclui o movimento do vim e a renderização de fórmulas matemáticas no VS Code da 2.1.301, mas ainda não inclui nenhum dos itens abaixo; por isso, o CHANGELOG é a fonte de cada um deles.²⁷⁵²⁷⁶

claude -p e o SDK voltam a iniciar no modo Manual. Uma sessão de claude -p ou do Agent SDK sem um modo de permissão definido agora inicia em default (Manual) com provedores de terceiros, com a telemetria desativada e em uma instalação nova; --permission-mode auto mantém o modo automático. Isso reverte a regra da v2.1.285, segundo a qual essas sessões iniciavam no modo automático, e mantém as sessões interativas do terminal e do VS Code como estavam: modo automático em todos os planos e provedores. A documentação dos modos de permissão ainda descreve o comportamento da v2.1.285. Veja Modos de permissão.²⁷⁵²⁷⁶

Subagents fork e padrões de execução em segundo plano. Os subagents fork (subagent_type: "fork") ficam ativados por padrão em claude -p, no Agent SDK, no aplicativo para desktop e no VS Code, como já acontecia no terminal; CLAUDE_CODE_FORK_SUBAGENT=0 os desativa, e claude mcp serve nunca os disponibiliza. O aplicativo para desktop e o VS Code agora sempre executam os subagents da conversa principal em segundo plano, como o terminal, em vez de deixar Claude escolher, enquanto as chamadas de Agent feitas por um subagent em claude -p, no SDK, no aplicativo para desktop e no VS Code são executadas em primeiro plano por padrão. Os hooks de prompt e de agente agora executam no máximo 12 hooks de um mesmo evento por vez; os demais aguardam sua vez. A documentação de variáveis de ambiente e de subagents ainda diz que o modo fork fica ativado apenas em sessões interativas. Veja O que são subagents?.²⁷⁵²⁷⁶

Modo automático e compactação. CLAUDE_CODE_AUTO_MODE_MODEL define o modelo usado pelo classificador do modo automático no lado do cliente; a variável não altera o modelo do modo automático no lado do servidor. Com o classificador no lado do servidor, uma conversa longa demais para a verificação de segurança agora é compactada, em vez de ter todas as chamadas de ferramentas verificadas negadas. /config ganha a opção Compactação por inatividade para desativar ou reativar a compactação por inatividade, e o aviso exibido após essa compactação explica como desativá-la. O erro “O prompt é longo demais” ao interromper um turno durante a compactação foi corrigido, e /autocompact e /effort salvam as configurações para o modelo correto quando um gateway identifica o Opus 4 ou 4.1 com um prefixo como anthropic/claude-opus-4-1.²⁷⁵

Claude Design será encerrado até 14 de dezembro de 2026. /design-sync e /design-login agora exibem um aviso de que a versão independente do Claude Design (claude.ai/design) será encerrada até essa data, e /design consent e /design revoke direcionam as sessões na nuvem para claude.ai/design/settings em vez de /design-login. Veja a linha de /design em Comandos de barra.²⁷⁵

Correções que vale conhecer. A ferramenta Read não carrega mais inteiramente na memória imagens de qualquer tamanho, nem pipes ou dispositivos com nomes de imagem: fontes de imagem acima de 128 MB são recusadas. Uma ferramenta adicionada durante a sessão e carregada novamente pelo ToolSearch ou após a compactação não causa mais uma falha de aproveitamento do cache de prompt. claude plugin e outros subcomandos aguardam a conclusão de uma gravação pendente de configurações antes de encerrar, para que uma alteração não seja mais perdida nem fique em um arquivo .tmp. Os marketplaces de plugins não são mais clonados novamente a cada atualização, e os plugins do git não exibem mais a versão “desconhecida”, quando o git usa o formato reftable para referências por padrão; o isolamento por worktree funciona no git 2.56 ou posterior quando um arquivo .git avulso aponta para um diretório inexistente. Servidores MCP que negociam a versão 2026-07-28 do protocolo, mas omitem resultType, ttlMs ou cacheScope, agora exibem suas ferramentas. As sugestões de prompt são omitidas após uma resposta cobrada em créditos de uso. As solicitações não falham mais com “diagnostics: Entradas extras não são permitidas” após a troca para Vertex ou Bedrock durante a sessão. A inicialização com muitos plugins está mais rápida, principalmente no Windows, e a gravação de arquivos em unidades exFAT ou FAT32 no Windows não é mais recusada.²⁷⁵

Sessões na nuvem e Claude Tag. A página de uma rotina exibe um banner explicando por que sua última execução não iniciou, como o limite da organização para sessões simultâneas na nuvem; “Voltar até aqui” funciona em todas as mensagens (runners auto-hospedados precisam da v2.1.246 ou posterior); uma execução que falhou no meio não é mais repetida desde o início uma hora depois; e o custo e o uso de uma sessão na nuvem não voltam mais a zero quando ela é retomada em um novo processo. As configurações de administração do Claude Tag foram reorganizadas nas abas Pacotes, Conectores, Skills e plugins e Canais; imagens HEIC, SVG, TIFF e BMP anexadas no Slack agora chegam ao Claude como arquivos; e a função de gerente agora também concede acesso ao Claude Tag no Slack quando a organização restringe esse acesso por função.²⁷⁵

Novidades da v2.1.301

Claude Code 2.1.301 foi lançado em 15 de outubro de 2026 (npm às 14:34 UTC; o lançamento no GitHub, às 19:22 UTC, traz os mesmos 51 itens do CHANGELOG canônico). A tag latest do npm passou para a 2.1.302 no dia seguinte, por isso os dois lançamentos são abordados juntos aqui.²⁷⁵

Novas tentativas sem supervisão ganham um limite de espera por cota de uso. CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS faz o modo de novas tentativas sem supervisão (CLAUDE_CODE_RETRY_WATCHDOG) encerrar uma solicitação ao atingir um limite de uso cuja cota demorará demais para ser renovada, em vez de esperar; a variável aparece ao lado de CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS na Referência de variáveis de ambiente. Também para operadores: ao trocar para um modelo com uma janela de contexto menor, o modelo anterior agora resume a conversa se ela for longa demais para o novo, em vez de gastar créditos de uso em um resumo sem perguntar; os aliases fable e best fazem uma nova tentativa com o modelo Fable anterior quando o mais recente não está disponível para sua organização; e uma conversa que passa por um gateway LLM cujas respostas identificam um modelo diferente do solicitado não é mais compactada repetidamente.²⁷⁵

Telemetria, vim e mods. Os eventos tool_decision do OpenTelemetry ganham classifier_verdict e permission_mode, permitindo distinguir as decisões do classificador do modo automático das regras de permissão, além de classifier_category, que identifica a regra integrada correspondente a um bloqueio do classificador, quando OTEL_LOG_TOOL_DETAILS=1. O modo vim ganha o movimento %: salte para o delimitador correspondente, usando-o sozinho ou com d, c ou y (a documentação do modo interativo já o inclui). Os mods ganham rows em Input para criar um campo de texto com várias linhas no terminal, em que Enter envia e Shift+Enter, ou uma barra invertida antes de Enter, inicia uma nova linha; o handler .catch de um hook de mod agora só é executado quando o hook lança uma exceção ou excede o tempo limite; $.env.set resolve com {} assim que a variável é definida ou removida, ou com { deny } explicando o motivo; $.model.fork não retorna mais nothing-to-fork antes da primeira resposta de um novo processo; e, no VS Code e nos aplicativos para desktop e dispositivos móveis, uma árvore exibida acima da caixa de diálogo de perguntas pode conter Markdown e até 48 linhas. Veja Mods e Modo vim.²⁷⁵²⁷⁶

Correções que vale conhecer. Sair não remove mais sem perguntar uma worktree criada por um hook WorktreeCreate quando ela pode conter commits que ainda não foram enviados. Grep e Glob informam um erro quando o programa de busca falha, em vez de “nenhum resultado”. Skills e comandos com muitos nomes de argumentos ou nomes muito longos não travam mais por vários segundos: apenas os primeiros 64 nomes, com até 64 caracteres cada, são preenchidos. A ferramenta Read não lê mais arquivos binários como .xlsm, .parquet, .epub e .heic como texto. As skills voltam a ser listadas para o modelo após /rewind. Uma chamada de ferramenta interrompida por uma mensagem enviada durante o turno, enquanto a permissão era verificada, não é mais informada ao modelo como rejeitada por você. Esc no modo vim não descarta mais uma resposta digitada no AskUserQuestion: o campo de texto livre aceita o modo NORMAL, e Esc só cancela a partir desse modo. Um disco cheio agora gera um erro que identifica o disco, em vez da mensagem enganosa “Execute /login”. Runners auto-hospedados iniciados pelo Slack podem anexar um repositório quando as configurações gerenciadas restringem servidores MCP (use deniedMcpServers para manter essas ferramentas desativadas). O VS Code renderiza fórmulas matemáticas em LaTeX nas respostas, incluindo blocos $$ e \[ ... \], e exibe um link “Obter mais uso” no banner de limite de uso para os planos Pro e Max.²⁷⁵

Novidades da v2.1.300

Claude Code 2.1.300 foi lançado em 14 de outubro de 2026, horas depois da 2.1.299: o npm publicou a versão às 14:27 UTC sob a tag next, o lançamento no GitHub veio às 18:24 UTC com os mesmos 88 itens do CHANGELOG canônico e, até o fim do dia, tanto latest quanto next no npm apontavam para a 2.1.300, enquanto stable passou da 2.1.287 para a 2.1.292. Nenhuma versão foi pulada.²⁷³ A ferramenta advisor chega à Claude Platform on AWS. /advisor agora funciona na Claude Platform on AWS; nenhum advisor é executado até você escolher um com /advisor, advisorModel ou --advisor, e CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 desativa a ferramenta. Em 14 de outubro, a página de documentação do advisor ainda listava a Claude Platform on AWS entre os provedores sem suporte. A ferramenta em si, que permite ao Claude consultar um segundo modelo em momentos de decisão, já existia antes desta versão e está descrita em A ferramenta Advisor.²⁷³²⁷⁴

Mods e telemetria. Os mods ganham decorações de prompt com virtualText (texto exibido na caixa de prompt que nunca entra no rascunho), $.ui.view({ agentId }) para mostrar a transcrição de um agente na visualização principal ($.ui.view({}) volta), uma propriedade dir em Text para linhas da direita para a esquerda e o hook prompt.change para mudanças na caixa de prompt que não são edições digitadas (uma entrada recuperada do histórico, uma limpeza, uma ação de desfazer ou um preenchimento por plugin); agent.spawn agora pode reescrever o prompt e o model de um agente de workflow, em vez de apenas recusá-lo, e a referência de mods indica que a causa rewritten em next.error.cause foi introduzida na v2.1.300. Os eventos api_request do OpenTelemetry separam as gravações de cache em cache_creation_5m_tokens e cache_creation_1h_tokens, os spans de rastreamento incluem atributos das convenções semânticas de GenAI, como gen_ai.provider.name, gen_ai.conversation.id, gen_ai.tool.name e error.type, e um prompt reescrito ou descartado pelo hook prompt.submit de um mod deixa de ser registrado como digitado no evento user_prompt. As transcrições locais agora também registram o prompt de sistema, as ferramentas e os parâmetros de cada requisição à API, para que uma transcrição compartilhada possa reproduzir uma requisição exatamente (veja Mods e Telemetria).²⁷³²⁷⁴

Mudanças operacionais e de comportamento. Requisições grandes para api.anthropic.com usam gzip mesmo com a telemetria desativada; CLAUDE_CODE_GZIP_REQUEST_BODIES=0 desativa essa compressão. O updatedInput dos hooks PreToolUse e PermissionRequest é validado como a entrada do próprio Claude: chaves desconhecidas são descartadas, e uma entrada rejeitada pela ferramenta impede a chamada. Ao sair, os comandos em segundo plano que ainda estiverem em execução 1,5 segundo após receberem a solicitação de parada são encerrados à força. claude remote-control remove as flags --sandbox e --no-sandbox, que não tinham efeito; passar qualquer uma delas encerra o comando com um erro, e sandbox.enabled nas configurações é a forma de executar essas sessões em sandbox. Sessões sob CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST ignoram, nas configurações, variáveis de pacote de certificados CA, proxy de ferramentas, TLS do git e configuração do git, como SSL_CERT_FILE. Nas sessões na nuvem do Cowork, o setMode de um hook PermissionRequest é ignorado, enquanto o restante da aprovação é aplicado. A aba Code do Claude Desktop aplica configurações gerenciadas quando forceLoginGatewayUrl especifica um gateway operado pela Anthropic que atende ao hostname da sessão, e claude gateway interrompe a inicialização ao encontrar uma chave de política desktop: que não pode usar. As opções de /sandbox exibem “Executar comandos em sandbox”. O VS Code ganha claudeCode.attachSelection para manter as seleções do editor fora das suas mensagens. No Slack, o Claude Tag pode responder em canais do Slack Connect quando um administrador permite.²⁷³

Correções que vale conhecer. Os hooks SessionEnd são executados quando você sai enquanto um comando em segundo plano ainda está em execução; ENABLE_TOOL_SEARCH=auto não é mais desativado no meio de uma conversa; um login recusado por forceLoginOrgUUID não deixa mais o token dessa organização armazenado; sessões headless e SDK retomadas após uma compactação mantêm as mensagens preservadas por ela e seu resumo; uma conversa não falha mais a cada turno com um erro 400 quando a API rejeita o esquema de entrada de uma ferramenta MCP (a ferramenta é enviada sem parâmetros); os hooks de agente respeitam seu model; sessões com --worktree começam no commit correto quando uma tag ou branch tem um nome igual a um ID de commit e voltam a abrir em repositórios reftable; claude daemon stop --any aguarda, encerra à força um serviço travado e sai com código 1 se ele ainda estiver em execução; Write e Edit em sessões na nuvem do Cowork não informam mais sucesso para um caminho no seu próprio computador; sessões na nuvem não travam mais por cinco minutos a cada turno quando não é possível ler a política da organização; e runners auto-hospedados não congelam mais quando ninguém lê sua saída.²⁷³

Novidades da v2.1.299

O Claude Code 2.1.299 foi lançado em 14 de outubro de 2026 (npm às 00:23 UTC; a versão publicada no GitHub às 02:49 UTC contém os mesmos 190 itens do CHANGELOG canônico). As versões 2.1.297 e 2.1.298 nunca foram publicadas, então nada foi omitido. A versão latest no npm foi a 2.1.299 até a 2.1.300 ser promovida mais tarde naquele dia (veja Novidades da v2.1.300).²⁷¹²⁷³ Atualize se você usa a 2.1.296: esta versão corrige duas regressões introduzidas nela — falhas em Edit e Retry nas sessões na nuvem do Cowork e do claude.ai ao lidar com uma mensagem interrompida enquanto seus hooks UserPromptSubmit ou prompt.submit de mods estavam em execução, e sessões na nuvem ou headless que executavam duas vezes uma chamada de ferramenta aprovada quando uma nova mensagem chegava durante a retomada da sessão após uma reinicialização.

Compactação por inatividade (v2.1.299). Uma conversa no terminal com 200 mil tokens ou mais que fica inativa por cerca de 54 minutos agora é compactada antes de seu cache de prompt de uma hora expirar, para que a próxima mensagem não reprocesse todo o contexto. CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS altera o mínimo de 200 mil (valores abaixo de 100.000 são elevados para 100.000), e "idleCompaction": false em settings.json desativa o recurso; a referência de configurações e a página de variáveis de ambiente listam ambos e indicam sua disponibilidade a partir da v2.1.290. CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 faz uma menção com @ fornecer ao Claude o caminho para leitura com suas ferramentas de arquivo, em vez do conteúdo do arquivo, para que seus hooks PreToolUse sejam executados na leitura; essa variável não pode ser definida nas configurações do projeto nem nas configurações locais (veja Referência de variáveis de ambiente).²⁷¹²⁷² A v2.1.302 adiciona uma opção Compactação por inatividade a /config para desativar ou reativar o recurso, e o aviso exibido após uma compactação por inatividade explica como fazer isso.²⁷⁵

Permissões e MCP. Uma regra de permissão como mcp__a agora abrange apenas o servidor chamado a, não a__b nem a_; escreva mcp__<server>__* com o nome normalizado completo do servidor e liste da mesma forma um servidor cujo nome contenha __ na lista tools: de um agente, que agora inclui apenas as ferramentas desse servidor. Regras de negação e de solicitação de confirmação para um servidor cujo nome normalizado contém um sublinhado duplo voltam a ser aplicadas. As descrições de ferramentas e as instruções de servidor dos servidores MCP da própria Anthropic em api.anthropic.com chegam ao Claude na íntegra, em vez de serem truncadas em 4.096 caracteres. Os conectores de sessões na nuvem e do Remote Control negociam o protocolo MCP 2026-07-28 por padrão em instalações que não obtêm flags (MCP_PROTOCOL_NEGOTIATION=legacy desativa esse comportamento), requisições ao proxy de conectores do claude.ai e aos servidores MCP hospedados pela Anthropic não seguem mais redirecionamentos HTTP, o MCP OAuth agora envia os valores configurados de headers e headersHelper, um .mcp.json vazio não é mais considerado inválido, e servidores chamados constructor ou prototype conseguem se conectar. Um comando executado em sandbox não pode mais gravar em uma pasta --plugin-dir nem acessar um caminho bloqueado por meio de um link simbólico, solicitações de confirmação para rm não são mais acionadas por um script de shell -c que não executa rm, e um rm montado em tempo de execução dentro de um script que o Claude Code não consegue ler só solicita confirmação com CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1.²⁷¹

Hooks e mods. Os hooks UserPromptSubmit são executados antes da expansão de uma skill ou de um comando de barra personalizado, então um hook que bloqueia o prompt também impede a execução dos comandos de shell incorporados, e o hook UserPromptSubmit do próprio front matter de uma skill é executado pela primeira vez no prompt seguinte ao que a invoca. Um hook de plugin que não consegue receber uma ação ou devolver sua resposta agora recusa a ação, em vez de permiti-la; se uma ferramenta já tiver sido executada, seu resultado é retido. Nos mods, o hook turn.start também recebe os turnos de subagents e de outros agentes da equipe (e.agentId permite distingui-los), skill.prompt recebe o front matter, a origem, o nome do plugin e o caminho do arquivo da skill (a referência de mods indica que esses campos foram introduzidos na v2.1.299), $.prompt.media permite que o hook prompt.submit de um mod de configurações gerenciadas leia uma imagem ou um documento anexado, $.session.identity() informa como a sessão está autenticada, Text aceita size, weight, mono e tabular, e Box aceita níveis de espaçamento nomeados (bold foi descontinuado em favor de weight), session.append ganha uma opção queue, e agent.spawn é acionado na retomada de um subagent ou de outro agente da equipe com resume definido. Mods desativados remotamente são descarregados entre turnos, e /plugin e claude plugin validate identificam os hooks ignorados em ambientes onde uma organização gerencia o Claude Code (veja Mods).²⁷¹²⁷² Comandos, interfaces e operações. /usage alerta sobre o nível de esforço max, workflows, contexto sempre ativo e resultados extensos de ferramentas. Na visualização de agentes, /effort e /fast definem as configurações iniciais das novas sessões, /model, /effort ou /fast sem argumentos abre um seletor, e o painel de prévia mostra uma linha de modo seguro para sessões iniciadas com --safe-mode. O modo de planejamento exibe um aviso uma única vez quando não vai pedir confirmação antes da maioria das edições porque a opção de ignorar permissões está disponível. claude plugin eval aceita --disallow-tools e um campo disallowed_tools por caso, e uma execução que termina com um erro de API recebe pontuação 0 e reprova a suíte. claude self-hosted-runner orchestrator --shutdown-drain-sec dá tempo para que consultas periódicas em andamento e hooks de criação de processos terminem ao receber SIGTERM. Ao usar um gateway de aplicativos Claude, CLAUDE_CODE_ATTRIBUTION_HEADER=0 no env de uma política code ou cli remove o bloco de atribuição. Nas sessões em nuvem do Cowork, um hook PermissionRequest não pode mais aprovar comandos de shell ou subagents no modo automático, e uma ação do Claude in Chrome sinalizada pelo classificador de segurança em um site aprovado pede sua confirmação em vez de ser recusada. O comando de retomada exibido ao sair identifica a sessão pelo ID; /btw em sessões não interativas atinge o tempo limite após 11 minutos; uma sessão local pode acompanhar 25 artefatos publicados, ante 10; e o aviso de proteção cibernética não pede mais que você se inscreva no Cyber Verification Program.²⁷¹

Correções que vale a pena conhecer. Streams por uma ANTHROPIC_BASE_URL personalizada aguardam dados por 300 segundos em vez de serem interrompidos aos 180; requisições de flags de recursos, inicialização, modo rápido, perfil e configurações gerenciadas pelo servidor para Anthropic não carregam mais a chave de API de um gateway de terceiros; /usage e a linha de status não mostram mais uso acima de 100%; tarefas agendadas e loops não são mais disparados novamente após cada turno durante a hora repetida no fim do horário de verão; a memória não cresce mais sem limite com --debug ou quando um processo pai para de ler stderr; SendMessage encontra um subagent pelo nome após uma reinicialização; Read processa arquivos UTF-16LE com marcador de ordem de bytes e Write se recusa a converter silenciosamente arquivos Windows-1252, Shift-JIS, GBK ou UTF-16BE para UTF-8; e, no Windows, hooks PreToolUse e PermissionRequest que não definem um shell bloqueiam a chamada quando o Git for Windows não está instalado, em vez de liberá-la em caso de falha.²⁷¹

Novidades nas versões v2.1.293-v2.1.296

Quatro versões foram lançadas entre 7 e 9 de outubro de 2026. No npm, latest e next estão na versão 2.1.296; stable passa de 2.1.285 para 2.1.287.²³⁸ O destaque é um novo modelo: Claude Haiku 5.5 chega na v2.1.293 como o modelo selecionado por haiku na API da Anthropic (consulte Modelos disponíveis). Atualize para a v2.1.296 se você faz login em um gateway de aplicativos Claude por meio de configurações gerenciadas: ela corrige uma regressão da v2.1.295 que ignorava um login salvo do gateway quando forceLoginMethod era gateway sem forceLoginGatewayUrl.

v2.1.296 (9 de outubro). As leituras de cache do Sonnet 5.5 passam a custar US$ 0,10 por milhão de tokens em /cost, na linha de status, em --max-budget-usd e nos valores de custo do SDK, que antes usavam US$ 0,20. O limite padrão das descrições de ferramentas MCP enviadas de início e das instruções de servidores MCP aumenta de 2.048 para 4.096 caracteres. O frontmatter de subagents e as definições de --agents aceitam autoCompactWindow, permitindo que um subagent compacte o contexto automaticamente antes da conversa principal. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL executa todos os agentes de workflow com um único modelo, enquanto os demais subagents mantêm os seus, e CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS define um intervalo máximo maior entre novas tentativas após erros 529. A ferramenta Read aceita allow_large, permitindo que Claude leia um arquivo de texto além do limite de tamanho habitual em uma única chamada quando houver espaço no contexto. Hooks PreToolUse de configurações gerenciadas que negam uma chamada de ferramenta com "continue": false, assim como hooks prompt gerenciados que bloqueiam uma chamada, agora também encerram o turno. --debug identifica campos de frontmatter não reconhecidos em arquivos de agentes personalizados e registra o comando, o plugin, o resultado e a duração de cada hook de comando. Um gateway de aplicativos Claude ganha uma chave code em managed.policies[], com as mesmas configurações de cli, também aplicadas na aba Code do Claude Desktop. Um turno ou comando ! iniciado enquanto ← move a sessão para segundo plano agora é interrompido em vez de terminar fora de vista. A documentação já foi atualizada para refletir duas dessas mudanças: a referência de hooks indica a v2.1.296 como a versão que introduziu as linhas de --debug por hook, e a documentação do gateway de aplicativos Claude descreve a chave de política code; autoCompactWindow e CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS foram incluídos na documentação de subagents e variáveis de ambiente até 14 de outubro; CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL continua aparecendo apenas nas notas de versão em 14 de outubro de 2026.^238240270272

v2.1.295 (8 de outubro). Hooks de comando e HTTP aceitam onFailure: "block": um hook que não consegue iniciar, atinge o tempo limite ou termina com um código inesperado bloqueia a ação em vez de permiti-la (consulte Protocolo de entrada/saída de hooks). CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS limita por quanto tempo o modo de novas tentativas sem supervisão aguarda a resolução de erros 429 e 529. Subagents pré-carregam no máximo 32 skills do campo skills, e descrições de ferramentas MCP carregadas pela busca de ferramentas são truncadas em 16.384 caracteres em vez de 2.048. forceLoginMethod: "gateway" e forceLoginGatewayUrl agora funcionam nas suas próprias configurações de usuário em uma máquina sem configurações gerenciadas, fazendo com que /login abra nesse gateway, uma configuração que a documentação do gateway agora descreve; cada upstream do gateway aceita uma lista opcional models, com * como curinga, e upstreams em nuvem respeitam timeouts.upstream_ttfb_ms. Terminais que implementam o Program Status Protocol (OSC 7501) podem mostrar se Claude Code está trabalhando, aguardando você ou se já terminou. Requisições em segundo plano por um gateway de aplicativos Claude usam Haiku 4.5 em vez do modelo da sessão quando o gateway o disponibiliza. Uma requisição para um modelo [1m] cuja opção beta context-1m é recusada por um gateway, Bedrock, Vertex ou Foundry é reenviada sem essa opção em vez de falhar. Ctrl+C no prompt ocioso de uma sessão em segundo plano à qual você está conectado mantém intacta uma reativação pendente de /loop, então pressioná-lo duas vezes desconecta você e o loop continua rodando; Esc o interrompe. Conectores do claude.ai negociam o protocolo MCP 2026-07-28 por padrão em instalações que não buscam flags. /copy oferece texto citado, claude -p informa em stderr o que está aguardando após o último turno, e mods ganham $.ui.notify. Buscas na web e avaliações de hooks agent não demoram mais tanto nos níveis de esforço xhigh e max.²³⁸²⁴⁰

v2.1.294 (8 de outubro). Duas correções para hooks prompt e agent escritos como instruções: um hook como “Bloqueie comandos que…” não permite mais o que deveria bloquear, e hooks Stop e SubagentStop como “Continue se o build estiver quebrado” são avaliados de modo que Claude tenha menos chance de parar antes da hora.²³⁸

v2.1.293 (7 de outubro). Claude Haiku 5.5 (claude-haiku-5-5) é o modelo Haiku padrão na API da Anthropic: contexto de 1M, US$ 0,10/US$ 0,50 por milhão de tokens, US$ 0,50/US$ 2,50 para prompts acima de 100K. O payload de subagentStatusLine ganha agentType, permitindo que um script de linha de status diferencie tipos personalizados de subagents; mods ganham isDeferred em $.tool.register. Duas mudanças foram revertidas: a mensagem de negação do modo automático da v2.1.281, que informava a Claude que uma negação abrange o resultado e não apenas o comando exato, e a correção da v2.1.290 para sessões em nuvem que perdiam uma reativação de /loop após a reinicialização de um contêiner, fazendo com que essas sessões voltem a permanecer inativas. Além disso: Claude não considera mais suas últimas ações antes de uma compactação como concluídas depois dela, uma conexão HTTP MCP não mantém mais todas as requisições enviadas até ser fechada, claude purge lista o que não conseguiu remover e termina com código 1 em vez de parar silenciosamente, a sincronização de skills do claude.ai verifica atualizações a cada 40 minutos em vez de 10 enquanto nenhuma sessão está em uso, e a inicialização nos planos Team e Enterprise busca a política e as configurações gerenciadas mais cedo, repetindo uma requisição travada após 3 segundos.²³⁸²⁴⁰

Novidades nas versões v2.1.288-v2.1.292

Cinco versões foram lançadas entre 2 e 6 de outubro de 2026. No npm, latest e next estão na versão 2.1.292; stable permanece na 2.1.285.²³⁴ Atualize se você está na 2.1.288, 2.1.289 ou 2.1.290: a v2.1.291 corrige uma regressão da 2.1.288 em que as últimas mensagens de uma sessão podiam se perder ao sair e uma regressão da 2.1.290 em que sessões em nuvem podiam descartar respostas a solicitações de permissão.²³⁵ v2.1.292 (6 de outubro). Definir CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS aumenta o atraso base do backoff nas novas tentativas de uma solicitação que retornou sobrecarga (529); a documentação de variáveis de ambiente agora informa o padrão, 500 ms, e o intervalo aceito, de 500 a 32000. A ferramenta Agent aceita um parâmetro effort, então Claude pode executar um subagent no nível de esforço que você solicitar; a documentação de subagents agora descreve esse parâmetro por chamada, que substitui o campo do frontmatter e continua em vigor quando o subagent é retomado, com CLAUDE_CODE_EFFORT_LEVEL tendo precedência sobre ambos. claude plugin install --marketplace <source> adiciona um marketplace e instala a partir dele em um único comando de shell. Os servidores MCP locais (stdio) agora negociam o protocolo 2026-07-28 por padrão em todas as instalações, incluindo Bedrock, Vertex e Foundry, com MCP_PROTOCOL_NEGOTIATION=legacy como opção para desativar esse comportamento; a documentação de MCP agora informa que essa revisão é solicitada por padrão aos servidores stdio. Os nomes de agentes têm um limite de 256 caracteres: nomes maiores são rejeitados, um name maior em um arquivo de skill ou plugin é ignorado, e a documentação de subagents agora informa o limite do campo name, com arquivos de subagents cujo nome excede o limite sendo ignorados e um erro sendo registrado no log de depuração. Uma correção de segurança impede que aprovações do hook PreToolUse e o modo automático contornem a solicitação de confirmação para leituras de arquivos em caminhos de rede (UNC). Os mods ganham prompt.autocomplete, cache de prompts em $.model.complete e agentes de fluxo de trabalho em agent.spawn, e claude plugin test agora falha quando a resposta do stub é uma recusa. Os demais itens constavam apenas nas notas de versão em 6 de outubro de 2026.^236237240

v2.1.290 (5 de outubro). A cota interativa do WebSearch é reposta a uma taxa de 100 chamadas por hora (CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR; 0 desativa a reposição), em vez de se esgotar após 200 chamadas. claude attach e claude logs aceitam parte do nome de uma sessão. /claude-api managed-agents-onboard <url> transforma uma página que descreve o padrão Managed Agents em arquivos ant apply, e /claude-api managed-agents-onboard <quickstart-name> cria um modelo de início rápido do Console, como deep-researcher, com a CLI ant. Vários padrões ficam mais restritivos: as configurações de um projeto não podem mais ativar Claude no Chrome, os arquivos .claude/settings.json ou .claude/settings.local.json de um repositório não podem mais definir CLAUDE_CODE_DISABLE_ATTACHMENTS, pyright e mais formas de ps pedem confirmação antes de executar, e um arquivo de configurações gerenciadas que aponta para fora da pasta de configurações gerenciadas gera um aviso. O WebFetch agora informa quanto do conteúdo de uma página além de 100.000 caracteres ficou sem leitura e aceita um offset para continuar a leitura, quando antes descartava esse texto silenciosamente. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC também pula o aquecimento da conexão na inicialização, e CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS=5m não é mais interpretado como 5 ms: valores com um sufixo de unidade usam a configuração dialogExpiry como alternativa.²³⁵²³⁷

v2.1.290, equipes e gateways. A página de aprovação de login do gateway de aplicativos de Claude ganha um botão Negar, e a versão mínima compatível do PostgreSQL cai de 14 para 11. Em runners auto-hospedados, claude --environment <id> cria sua sessão pela API Sessions atual. claude --teleport e /teleport recusam um stash que excluiria arquivos de uma pasta que substituiu um arquivo rastreado de mesmo nome, e o relay de --channels ignora um ID de resposta repetido em vez de aprovar uma solicitação diferente. No Slack, !fast coloca uma conversa no modo rápido e !fast off volta ao modo anterior. O VS Code mostra os horários das mensagens por padrão (a configuração Claude Code: Mostrar horários das mensagens desativa a exibição).²³⁵

v2.1.289 (3 de outubro). Os mods ganham agent.spawn para colegas de equipe, um único ID de agente entre os eventos de hooks de plugins e estados de inatividade e espera em $.agent.list(); claude plugin validate não ignora mais um plugin cuja pasta também contém um manifesto de marketplace; e duas brechas nas regras de negação de Bash com permissão automática no sandbox são corrigidas.²³⁵²³⁷

v2.1.288 (2 de outubro). claude project purge agora é claude purge; o nome antigo continua funcionando e exibe um aviso. O limite de tempo para comandos em segundo plano se aplica apenas a sessões sem supervisão (-p, a SDK Agent, CI, nuvem). /code-review --max-findings <n>|all altera o limite de achados até você passar --max-findings default. /autocompact salva sua janela por modelo. CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS desativa as saídas estruturadas para o Mantle ou gateways que as rejeitam. Regras com escopo por caminho e arquivos CLAUDE.md aninhados são carregados em Write e Edit, não apenas em Read. Servidores de linguagem atingem o tempo limite após 60 segundos (requestTimeout por servidor) em vez de ficarem travados. No modo automático, uma conversa longa demais para o classificador do lado do cliente é compactada em vez de gerar uma solicitação de confirmação a cada chamada de ferramenta, e o classificador do lado do cliente ignora uma versão fixada por ANTHROPIC_DEFAULT_SONNET_MODEL que indique Claude Sonnet 5.5 ou Opus 5.5 e usa Claude Sonnet 5. Os mods ganham $.ui.selection(), sessões na nuvem sem a CLI de GitHub ganham um gh api integrado, e pressionar a seta para cima em um prompt vazio restaura um rascunho apagado por Ctrl+C.²³⁴²³⁷

Novos comandos nas versões v2.1.105–v2.1.114¹⁴⁶¹⁵⁰

Resumo da sessão (v2.1.108+)

Um novo recurso por sessão que apresenta o contexto quando você retorna a uma sessão pausada. Ativado por padrão, pode ser desativado em /config ou com CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. O modelo também pode invocar comandos de barra integrados (/init, /review, /security-review) pela ferramenta Skill — ampliando o padrão de subagent/skill.¹⁴⁶

Notificações push (v2.1.110+)

Quando o Remote Control está configurado com “Enviar push quando Claude decidir” ativado, Claude agora pode enviar notificações push para dispositivos móveis a seu critério por meio de uma nova ferramenta de notificações push. O recurso se integra à interface móvel/web existente do Remote Control.¹⁴⁶ /context, /exit e /reload-plugins agora também funcionam em clientes Remote Control.

Ferramenta Windows PowerShell (v2.1.111+, liberação gradual)

Claude Code está disponibilizando gradualmente uma ferramenta nativa do Windows PowerShell. No Linux/macOS, ative-a com CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requer pwsh no PATH). No Windows, a mesma variável controla a ativação/desativação durante a liberação gradual.¹⁴⁶

Aprovação automática no modo de permissão (v2.1.119+). Os comandos da ferramenta PowerShell agora podem receber aprovação automática no modo de permissão da mesma forma que os comandos Bash. Regras de permissão como PowerShell(Get-*:*) e a sintaxe de padrões existente agora dispensam a solicitação de confirmação para operações somente de leitura, oferecendo a mesma praticidade que as equipes já têm no Linux/macOS.¹⁵²

Redução de permissões: Bash somente de leitura (v2.1.111+)

Padrões de Bash somente de leitura com argumentos glob (por exemplo, ls *.ts, cat src/*.md) e comandos que começam com cd <project-dir> && não acionam mais uma solicitação de permissão.¹⁴⁶ Em conjunto com /less-permission-prompts, isso deve reduzir bastante as interrupções nos fluxos de trabalho do dia a dia.

Rastreamento distribuído (v2.1.110+)

SDK e sessões headless agora leem TRACEPARENT e TRACESTATE do ambiente, vinculando execuções do Claude Code a rastreamentos distribuídos. Combine com OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir os corpos completos das requisições e respostas da API como eventos de log do OpenTelemetry para depuração.¹⁴⁶

Distribuição de binários nativos (v2.1.113+)¹⁵⁰

A v2.1.113 muda a forma como a CLI é iniciada: claude agora inicia um binário nativo do Claude Code por meio de uma dependência opcional específica de cada plataforma, em vez de executar o JavaScript incluído no pacote. Os comandos de instalação e atualização continuam iguais, e as equipes não precisam alterar os scripts de implantação.

Atalhos do editor de prompts (v2.1.113+)¹⁵⁰

O editor de prompts ganha navegação no estilo readline na entrada de várias linhas, além de rolagem da área de visualização em tela cheia:

Tempo limite para subagents parados (v2.1.113+)¹⁵⁰

Subagents que param de responder durante o streaming agora encerram com um erro claro após 10 minutos, em vez de ficarem travados em silêncio. Combine com CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para ampliar a cobertura de processos travados em APIs com streaming.

Correção de estabilidade da v2.1.114¹⁵⁰

A v2.1.114 (18 de abril de 2026) traz uma única correção: a caixa de diálogo de permissões podia falhar quando um integrante de agent-teams solicitava permissão para usar uma ferramenta. Atualize se você usa Agent Teams.

Marcação de conteúdo: marcas d’água em texto e metadados C2PA em arquivos (agosto de 2026)

A Anthropic anunciou uma marcação legível por máquina para conteúdo gerado pelo Claude, motivada pelo Artigo 50 do Regulamento de IA da UE (aplicável a partir de 2 de agosto de 2026 a sistemas de IA recém-lançados). O sistema tem dois componentes: uma marca d’água estatística invisível no texto gerado e metadados de proveniência assinados — conforme o padrão aberto C2PA — em arquivos gerados, como .svg, .png e .jpg.²⁵²²⁰⁴ O detalhe que as manchetes deixam pouco claro: os dois componentes seguem o mesmo cronograma por modelo. Segundo a página de suporte, “os modelos Claude lançados a partir de 2 de agosto de 2026 terão suporte à marcação legível por máquina desde o lançamento” — os modelos lançados antes dessa data, que representam toda a linha atual (Fable 5, Opus 5, Sonnet 5, Haiku 4.5), estão no período de transição da legislação da UE, e a Anthropic está “trabalhando para adicionar suporte à marcação também a esses modelos”.²⁰⁴

Essa lista é de agosto. Fable 5.1 (1º de setembro), Opus 5.5 (22 de setembro) e Sonnet 5.5 (28 de setembro) foram lançados após a data de corte, então a regra exige que tenham marcação desde o lançamento; as notas de lançamento do Fable 5.1 incluem a proveniência de conteúdo entre as novidades, enquanto a página do modelo e o guia de migração do Opus 5.5, assim como a página do modelo e a página de novidades do Sonnet 5.5, não mencionam a marcação.^241222230 O conteúdo gerado pelos modelos anteriores a agosto não tem marcação, seja em texto ou em arquivos; o conteúdo dos modelos mais recentes terá, em todas as interfaces — Claude Platform (API), claude.ai, Claude Code, Claude Cowork, Claude Tag e os gateways de nuvem —, já que a marcação ocorre no nível do modelo. Vale explicitar uma consequência disso, porque uma discussão que viralizou inverteu a lógica: qualquer mudança de estilo ou comportamento que você perceba em um dos modelos anteriores a agosto não pode ser causada pela marca d’água, pois a marcação não está ativa nesses modelos.

Como funciona: uma variante do SynthID-Text do Google DeepMind. A marca d’água altera “a fonte da aleatoriedade usada para escolher entre palavras” quando o Claude escolhe entre opções semanticamente equivalentes — sem adicionar caracteres, sem pós-processamento e, segundo os testes internos da Anthropic, “sem impacto da marca d’água no conteúdo, no nível de criatividade ou na legibilidade”.²⁵²

O que interessa a quem usa o Claude Code: o código contém uma marca d’água esparsa. Código funcional deixa pouco espaço para escolhas arbitrárias, então a marca se concentra onde há liberdade — comentários, nomes —, com o que a Anthropic chama de “um efeito insignificante no código efetivamente produzido”.²⁵² A durabilidade é probabilística e varia por componente: no texto, pequenas edições “provavelmente não removerão a marca d’água por completo”, uma reescrita completa a removerá, e uma tradução produzida pelo Claude terá sua própria marca nova; nos metadados de arquivos, conversões de formato, novos salvamentos e capturas de tela podem remover a assinatura C2PA.²⁰⁴ Há planos para uma API de detecção; um resultado positivo comprova que “o Claude provavelmente esteve envolvido com o conteúdo em algum momento” e explicitamente não permite distinguir entre “o Claude escreveu isto” e “o Claude editou isto substancialmente” — e, segundo a página de suporte, uma marca ausente também não comprova nada. Não há menção à possibilidade de desativar a marcação em nenhum plano de cliente.²⁵²²⁰⁴

Quanto custa o Claude Code?

Entender e controlar os custos é essencial para usar o Claude Code de forma sustentável. Consulte também Seleção de modelo para conhecer os recursos dos modelos e Estruturas de decisão para escolher o modelo certo para cada tarefa.

Como visualizar os custos

> /cost

Saída:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Usuários de assinaturas veem em /cost um detalhamento por modelo e acertos de cache, mostrando exatamente quais modelos consumiram tokens e quanto foi servido pelo cache (v2.1.92+).¹³⁷

Tarifas contratadas em vez do preço de tabela (modelPricing, gerenciado, v2.1.243+): organizações com tarifas negociadas por modelo ou um multiplicador de desconto podem implantá-los como a configuração gerenciada modelPricing; /cost, a linha de status e os valores de custo da telemetria passam a usar essas tarifas em vez do preço de tabela, para que os números vistos pelos desenvolvedores correspondam ao que a organização paga.²⁵⁰ Desde a v2.1.271, o multiplicador também pode ser superior a 1 — até 10 — para organizações que cobram das equipes internas tarifas com acréscimo.²¹⁶

Linha de cache de prompts por sessão (v2.1.251+): /cost adiciona uma linha de cache de prompts para a sessão — taxa de acertos, falhas, tokens armazenados novamente em cache e se o cache está quente ou frio — acompanhada por um objeto prompt_cache correspondente para scripts da linha de status. O objeto aparece após a primeira resposta do API da conversa principal, não contabiliza solicitações de subagents e é calculado com base nas contagens de tokens de cache nas respostas do API, por isso funciona com todos os provedores. /usage mostra as mesmas estatísticas em sua linha Prompt cache (main).²⁰⁶²⁰⁹ Desde a v2.1.260, a linha de /cost e o objeto prompt_cache da linha de status também indicam uma causa provável para as falhas de cache — por exemplo, mudanças nas definições das ferramentas ou no prompt do sistema, ou inatividade da sessão além do TTL do cache.²¹²

O tráfego de agentes não interrompe mais o próprio prefixo de cache (v2.1.265): duas correções eliminam vazamentos do cache de prompts em trabalhos delegados. Retomar um subagent iniciado em primeiro plano não altera mais sua lista de ferramentas nem o prefixo do prompt do sistema, e os integrantes de equipes de agentes e subagents retomados não retiram mais do prefixo do prompt, nos turnos posteriores, o contexto do hook SubagentStart e as skills pré-carregadas. Ambos os bugs impediam a reutilização do cache de prompts — o prefixo mudava, então tudo depois dele era reenviado como entrada não armazenada em cache — justamente nas longas sessões com agentes em que a economia do cache é mais importante (o mesmo modo de falha corrigido pela v2.1.260 nos turnos de chamadas de ferramentas do Fable 5.1).²¹⁵

O conjunto de melhorias na estabilidade do cache da v2.1.267: uma versão, cerca de dez correções, todas para o mesmo modo de falha — algo reescrevia o prefixo do prompt durante a conversa, e tudo depois dele era reenviado como entrada não armazenada em cache. Sessões retomadas não reescrevem mais listas de ferramentas, renderizam novamente descrições de ferramentas nem reescrevem avisos anteriores sobre ferramentas do MCP antes que seus conectores sejam reconectados; trocar de modelo com /model não reenvia mais todas as definições de ferramentas (o texto de atribuição de commits e PRs agora chega como uma nota da conversa, atualizada quando o modelo muda); subagents e sessões iniciadas com --system-prompt ou --append-system-prompt registram o prompt do sistema e as definições de ferramentas uma única vez; e ferramentas do MCP e de plugins disponibilizadas durante a sessão chegam a sessões sem ToolSearch como definições adiadas, em vez de uma lista de ferramentas reescrita. Esse conjunto amplia as correções das versões v2.1.260 e v2.1.265 para retomadas, trocas de modelo e reconexões do MCP.²¹⁶

A v2.1.273 mantém a continuidade da conversa: /login, /upgrade e /extra-usage descartavam raciocínios anteriores da conversa, o que forçava uma reescrita completa do cache de prompts na solicitação seguinte.²¹⁷

A v2.1.277 elimina mais três vazamentos de prefixo: sessões continuadas depois de /clear (reinicialização, --continue, --resume) perdiam parte da primeira mensagem quando um hook SessionStart gerava uma saída, causando uma falha completa do cache de prompts; subagents e integrantes de equipes retomados renderizavam novamente as definições das ferramentas do MCP que haviam carregado, o que interrompia o cache de prompts desse agente; e anexos registrados anteriormente em uma conversa eram renderizados novamente após uma retomada ou reinicialização, descartando o raciocínio estendido e perdendo o cache de prompts. É o mesmo modo de falha dos conjuntos das versões v2.1.265–267 — algo reescrevia o prefixo e todo o conteúdo posterior era reenviado sem cache — agora abrangendo a saída de SessionStart, as definições do MCP para agentes retomados e os anexos registrados.²¹⁹

A v2.1.280 adiciona mais duas correções: uma troca de modelo feita em um aplicativo host (Claude Desktop, VS Code, o SDK) enquanto o Claude está trabalhando não causa mais uma falha do cache de prompts na solicitação seguinte, e um subagent bifurcado retomado agora reenvia a lista de ferramentas que usou inicialmente em vez de recriá-la, o que interrompia o cache de prompts desse agente.²²⁰

A v2.1.281 adiciona mais três correções: uma sessão retomada depois de uma reinicialização durante uma solicitação de permissão pendente não envia mais um histórico diferente do anterior, o que interrompia o cache de prompts a partir desse ponto; um servidor MCP que se desconecta durante a conversa, ou que ainda está se conectando depois de uma retomada, não prejudica mais o cache quando a busca de ferramentas está desativada (por exemplo, atrás de um proxy ou gateway); e as sessões retomadas não reenviam mais turnos anteriores em um formato alterado, o que poderia fazer o API descartar o raciocínio anterior da conversa.²²⁴

Planos de assinatura

Limites de taxa (agosto de 2025): a Anthropic introduziu limites de taxa semanais para assinantes pagantes. Assinantes Max podem comprar uso adicional além do limite de taxa pelas tarifas padrão do API.¹⁴

Limites de taxa dobrados (6 de maio de 2026): durante o evento Code with Claude SF, a Anthropic dobrou os limites de cinco horas do Claude Code nos planos Pro, Max, Team e Enterprise por licença, removeu a redução nos horários de pico das contas Pro e Max e aumentou “consideravelmente” os limites de taxa do API para os modelos Claude Opus. A garantia de capacidade é o acordo com o SpaceX Colossus 1: “mais de 300 megawatts de nova capacidade (mais de 220.000 GPUs da NVIDIA) em um mês”.¹⁵⁷

Limites semanais a partir de 14 de setembro de 2026 (anunciados em 29 de agosto): o aumento temporário de 50% nos limites semanais, vigente desde o aumento de maio, termina em 14 de setembro e será substituído por um aumento permanente de 25% sobre a referência anterior ao aumento nos planos Pro, Max, Team e Enterprise por licença. Segundo os cálculos da própria Anthropic sobre a mudança: “Em comparação com hoje, isso representa uma redução de 17% nos limites semanais do Claude Code.” Se seu teto semanal atual for de 150 unidades, ele passará a 125 em 14 de setembro. Os limites de cinco horas não fazem parte deste anúncio; o aumento de maio continua valendo. Planeje-se desde já para o teto menor caso você execute sessões longas sem supervisão: a opção de continuar automaticamente após a redefinição (v2.1.234) e /usage são os dois controles relevantes.²¹³

Preços dos tokens do API (outubro de 2026)^1144222239

Para usuários cobrados pelo API, preços por milhão de tokens:

Preço para contexto de 1 milhão (abril de 2026): Opus 4.7, Opus 4.6, Sonnet 4.6 e Mythos Preview incluem 1 milhão de tokens pelas tarifas padrão por MTok — sem acréscimo por contexto longo.¹⁴⁸ Essa é uma consolidação recente; a orientação anterior de que Opus 4.6 ou Sonnet 4.6 custavam 2× na entrada e 1,5× na saída acima de 200 mil tokens de entrada não é mais válida. O Opus 4.5 legado e os modelos anteriores mantêm suas estruturas de preços originais.

Preço por residência de dados: especificar inferência somente nos EUA por meio de inference_geo adiciona um multiplicador de 1,1× a todos os preços de tokens, inclusive leituras e gravações de cache (modelos Opus 4.6+).¹⁴⁸

O cache de prompts reduz significativamente os custos de entradas repetidas: as gravações de cache custam 1,25× a tarifa-base (cache de 5 minutos) ou 2× (cache de 1 hora), mas as leituras de cache custam apenas 0,1×, uma economia de 90%. Duas exceções têm preços ainda menores: as leituras do Claude Opus 5.5 custam 0,05× (US$ 0,20/MTok, uma economia de 95%), e as do Claude Fable 5.1 e Mythos 5.1 custam 0,025× (US$ 0,25/MTok no Fable 5.1, uma economia de 97,5%).²⁴¹²²² Para sistemas RAG e assistentes de programação com contexto repetido, o cache pode reduzir os custos em 88–95%.

O API em lote oferece 50% de desconto com prazo de até 24 horas para tarefas não urgentes, como suítes de testes executadas durante a noite.

Política para várias contas⁵²

Você pode ter várias contas do Claude? Sim, para casos de uso legítimos. A Anthropic permite explicitamente várias contas quando elas atendem a finalidades distintas.

O que é permitido:

Limites técnicos: - Até 3 contas podem ser verificadas com o mesmo número de telefone - Várias assinaturas pagas no mesmo IP ou na mesma rede são explicitamente compatíveis - As contas são totalmente separadas; não é possível transferir chats ou projetos entre elas

O que é proibido (de acordo com a Política de Uso): - Criar contas para contornar banimentos depois de ser banido - Coordenar atividades maliciosas entre contas para evitar a detecção - Usar várias contas para contornar limites de taxa ou créditos do plano gratuito

Observação do mundo real: em janeiro de 2026, o usuário avançado Jeffrey Emanuel (@doodlestein) teve suas 22 contas Max sinalizadas automaticamente e temporariamente banidas. Thariq (@trq212), funcionário da Anthropic, resolveu o problema em até 4 horas após confirmar o uso legítimo. Se você usa muito o Claude Code em projetos profissionais e pessoais com várias contas, é exatamente para isso que o serviço foi projetado, mas não tente manipular o sistema.

Em caso de dúvida: entre em contato com o Suporte da Anthropic para obter uma confirmação por escrito sobre sua configuração específica.

Fatores de custo

Exemplos de custos reais

Custos pelos preços de tabela (US$ 0,10/US$ 0,50 para o Haiku 5.5 em prompts de até 100 mil tokens, US$ 2/US$ 10 para o Sonnet 5.5 e US$ 4/US$ 20 para o Opus 5.5 por MTok), antes dos descontos de cache de prompts.

Dica para economizar: usar Haiku para subagents de exploração e Sonnet para implementação normalmente reduz os custos em 40–50% quando comparado ao uso do Sonnet para tudo.

Gerenciamento de custos da equipe

TPM/RPM recomendados por tamanho da equipe:

Taxas ocultas de ferramentas

Além do preço por token, algumas ferramentas geram cobranças separadas:⁹

Esses custos se acumulam nos loops de agentes. Um ciclo de depuração com 100 iterações usando Bash custa cerca de 24.500 tokens de entrada extras apenas em sobrecarga.

Estratégias para economizar

1. Use Haiku para subagents: a maior parte da exploração não precisa do Sonnet
2. Ative o cache de prompts: ele vem ativado por padrão, mas verifique se não foi desativado
3. Defina o máximo de turnos: claude --max-turns 5 evita conversas descontroladas
4. Defina um limite em dólares: claude --max-budget-usd 5 interrompe a sessão ao atingir um teto de gastos. Desde a v2.1.217, o limite também controla subagents em segundo plano — quando ele é atingido, novas inicializações são recusadas e agentes em segundo plano que estejam em execução são interrompidos (antes, esses agentes não respeitavam o orçamento)¹⁹⁴
5. Use o modo de planejamento para exploração: sem execução = sem operações caras acidentais
6. Faça a compactação de forma proativa: menos contexto = menos tokens
7. Limite a saída: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. Use o API em lote para trabalhos não urgentes: 50% de desconto nos tokens de entrada e saída
9. Analise os gastos do API do Claude em um projeto: /claude-api cost-optimize (v2.1.247+) analisa os gastos do API do Claude em um projeto existente e percorre os mecanismos de redução de custos (cache, uso eficiente de tokens, lote, esforço e escolha de modelo), aplicando uma alteração mensurada por vez — para os aplicativos que você cria com o API, não para a própria sessão do Claude Code²⁴⁵

Monitoramento do uso

• Console do Claude: platform.claude.com (exige a função Admin ou Billing)
• Limites do workspace: defina limites de gastos por workspace
• Bedrock/Vertex: use o monitoramento de custos nativo da nuvem
• LiteLLM: para o acompanhamento detalhado por usuário com provedores terceiros

Uso de tokens em segundo plano

Algumas operações consomem tokens em segundo plano: - Resumo de conversas para /resume - Comandos /cost e /status - Compactação automática

Normalmente, menos de US$ 0,04 por sessão.

API de análise do Claude Code (Team/Enterprise)⁴⁶

Acesse de forma programática as análises de uso e as métricas de produtividade do Claude Code da sua organização por meio do API de administração.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Chave do API de administração (sk-ant-admin...) - Plano Team ou Enterprise - Função Admin, Billing ou Developer

Métricas disponíveis:

Exemplo de solicitação:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Casos de uso: - Análise da produtividade dos desenvolvedores (sessões, commits, PRs) - Métricas de uso das ferramentas (taxas de aceitação/rejeição para Edit, Write etc.) - Acompanhamento e alocação de custos entre equipes - Justificativa do ROI para ferramentas de programação com IA

Observação: os dados aparecem até 1 hora após a conclusão da atividade. Para garantir a consistência, somente dados com mais de 1 hora são incluídos nas respostas.

Estruturas de decisão

Conhecer os recursos não é suficiente. Você precisa saber quando usar cada um. Estas árvores de decisão transformam conhecimento em ação.

Qual modelo devo usar?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 5.5 (medium effort default; /effort high or xhigh for harder)
                  │         Cost: ~$1.60/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.50/task
                           Balance: Best overall when cost matters

Regra geral: desde a v2.1.280, o padrão não segue mais o seu plano — toda sessão começa no Opus 5.5, exceto no Microsoft Foundry —, então a ação que antes era “mudar para o Opus” agora é o inverso: /model sonnet reduz o modelo pela metade do preço por token quando uma tarefa não precisa desse nível de raciocínio.^{181197207220221} Use o Haiku para subagents. Continue no Opus quando uma resposta de um modelo inferior parecer superficial. Com agent teams (v2.1.32+), o Opus pode coordenar vários agentes trabalhando em paralelo em diferentes subtarefas.⁷⁹

Comando, skill, subagent ou agent team?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook ou prompt?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

Quando usar raciocínio estendido?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

Ative ou desative com Alt+T durante a sessão. Orçamentos maiores de raciocínio custam mais; comece com o mínimo e aumente apenas se as respostas parecerem apressadas.

Raciocínio adaptativo do Opus 4.6: o Opus 4.6 ajusta automaticamente a profundidade do raciocínio com base na complexidade do problema. Para a maioria das tarefas, não é necessário controlar explicitamente o orçamento de raciocínio — o Opus aumenta a capacidade para problemas difíceis e continua rápido nos simples. A alternância manual do raciocínio é mais útil com o Sonnet quando você quer forçar uma análise mais profunda.

Qual superfície de execução usar?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent teams, subagents ou sessões paralelas

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL