Quem acompanha o ritmo de atualizações do Claude Code sabe que as releases menores costumam carregar mudanças que parecem pequenas no changelog, mas têm impacto real no dia a dia de quem constrói pipelines com agentes. A versão v2.1.211, publicada pela Anthropic no GitHub, é um bom exemplo disso: três itens no “What’s changed”, três áreas críticas tocadas — observabilidade, segurança e controle de fluxo de hooks. Vamos destrinchar cada uma.
1. --forward-subagent-text: enxergando o que os subagentes estão pensando
Quem usa Claude Code em arquiteturas multiagente — um agente orquestrador delegando tarefas para subagentes especializados — já deve ter se deparado com uma caixa-preta inconveniente: o output em formato stream-json simplesmente não incluía o texto e o raciocínio gerados pelos subagentes. Você via o resultado final, mas o caminho percorrido ficava invisível.
A v2.1.211 resolve isso com o novo flag --forward-subagent-text (e sua contraparte em variável de ambiente, CLAUDE_CODE_FORWARD_SUBAGENT_TEXT). Com ele ativado, o stream JSON passa a incluir tanto o texto quanto o thinking dos subagentes, propagando essas informações de volta para o output do processo principal.
Por que isso importa na prática?
Imagine um pipeline em que o agente orquestrador divide uma tarefa de refatoração de código em subtarefas: um subagente analisa dependências, outro reescreve funções, um terceiro escreve os testes. Sem --forward-subagent-text, seu sistema de logging ou monitoramento só captura o output consolidado — bom para o resultado, ruim para depuração.
Com o flag ativo, você consegue:
- Auditar o raciocínio de cada subagente individualmente
- Identificar gargalos de latência em etapas específicas do pipeline
- Depurar decisões erradas rastreando em qual subagente o raciocínio saiu dos trilhos
- Alimentar sistemas de observabilidade (como LangSmith, Langfuse ou soluções próprias) com dados granulares
Para ativar via linha de comando:
claude --output-format stream-json --forward-subagent-text "sua tarefa aqui"Ou via variável de ambiente, útil para configurações de CI/CD ou containers:
export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=true
claude --output-format stream-json "sua tarefa aqui"Atenção: o flag só faz sentido quando combinado com
--output-format stream-json. Sem o formato de streaming JSON ativo, não há stream a ser enriquecido.
Essa mudança é especialmente relevante para equipes que estão profissionalizando o uso de agentes em produção. Observabilidade deixou de ser opcional quando você coloca agentes para tomar decisões em nome do negócio.
2. Correção de segurança: neutralizando caracteres invisíveis nos previews de permissão
Esse é o item mais sério da release — e merece atenção especial de qualquer um que use Claude Code em ambientes onde as ferramentas processam inputs externos, sejam arquivos, APIs ou qualquer dado que não esteja completamente sob seu controle.
O problema corrigido estava nos previews de permissão — aquelas mensagens que o Claude Code exibe pedindo sua aprovação antes de executar uma ação de ferramenta. A ideia é simples: mostrar o que está prestes a acontecer para que o usuário decida se aprova ou não. O problema é que, antes da correção, esses previews não sanitizavam certos tipos de caracteres Unicode potencialmente maliciosos:
- Bidirectional-override characters (como
U+202E, Right-to-Left Override): conseguem inverter a direção de leitura de texto, fazendo com que uma string exibida da esquerda para a direita seja lida como se fosse da direita para a esquerda — um truque clássico para esconder extensões de arquivo maliciosas ou comandos perigosos. - Zero-width characters: caracteres invisíveis que não ocupam espaço visual, mas existem na string. Podem ser usados para fragmentar palavras-chave e enganar filtros de texto.
- Look-alike quote characters: versões Unicode de aspas que se parecem visualmente com aspas comuns (
",') mas são caracteres diferentes, podendo alterar a semântica de um comando sem que o usuário perceba.
O vetor de ataque que isso fechou
O cenário de exploit é elegante e assustador: um arquivo malicioso, uma resposta de API controlada por um atacante ou qualquer outro input de ferramenta poderia conter esses caracteres de forma estratégica. Quando o Claude Code exibisse o preview pedindo sua aprovação, o texto que você veria seria diferente do que seria executado. Você aprovaria uma ação acreditando estar vendo uma coisa; a ferramenta executaria outra.
É um ataque de engenharia social mediado por Unicode — e é exatamente o tipo de vetor que cresce em relevância à medida que agentes ganham mais autonomia para lidar com dados externos.
A correção da Anthropic garante que esses caracteres sejam neutralizados antes de chegarem à interface de aprovação. O que você vê no preview é agora uma representação fiel e segura do que será executado.
O que você deve fazer?
Se você usa Claude Code em ambientes que processam dados de fontes externas — especialmente arquivos enviados por usuários, respostas de APIs de terceiros ou conteúdo raspado da web — atualize imediatamente para v2.1.211 ou superior. Esse não é um fix cosmético.
3. Hooks PreToolUse com decisão ask: o modo automático não manda mais
O terceiro fix é mais técnico, mas tem impacto direto em quem usa o sistema de hooks do Claude Code para implementar camadas de controle customizadas.
Contexto: o que são hooks no Claude Code?
Hooks são pontos de extensão que permitem que você injete lógica própria no ciclo de execução do Claude Code. O hook PreToolUse, especificamente, é disparado antes de uma ferramenta ser executada, e pode retornar uma decisão com três valores possíveis: allow (prossiga), block (bloqueie) ou ask (pergunte ao usuário).
O valor ask é particularmente útil quando você quer que certas ações — especialmente comandos Bash potencialmente destrutivos — passem por aprovação humana, mesmo quando o Claude Code está rodando em modo automático (aquele em que ele não pede confirmação para cada passo).
O bug e a correção
Antes da correção, havia um conflito de precedência: quando o Claude Code estava em modo automático e a ferramenta era Bash sem sandbox, o modo automático simplesmente sobrescrevia a decisão ask do hook PreToolUse, prosseguindo sem pedir confirmação ao usuário.
Em outras palavras, seu hook falava “ei, preciso de aprovação humana aqui” e o modo automático respondia “sem problemas, vou aprovar sozinho” — esvaziando completamente o propósito do hook.
A v2.1.211 corrige isso estabelecendo que ask é um piso, não uma sugestão. Se um hook PreToolUse retorna ask, essa decisão será respeitada independentemente do modo de operação. O modo automático pode elevar uma decisão allow para execução direta, mas não pode rebaixar um ask para allow.
Exemplo de uso prático
Imagine um hook que monitora comandos Bash e exige aprovação sempre que detecta operações de deleção:
// hook PreToolUse simplificado
export default function preToolUse({ tool, input }) {
if (tool === "bash" && /rm\s+-rf|rmdir|del\s+\//.test(input.command)) {
return { decision: "ask", reason: "Comando destrutivo detectado. Confirme antes de prosseguir." };
}
return { decision: "allow" };
}Antes do fix, rodar Claude Code com --dangerously-skip-permissions ou em modo automático simplesmente ignoraria esse hook para Bash sem sandbox. Agora, o ask é honrado.
Isso é especialmente relevante para times que usam hooks como camada de compliance — garantindo, por exemplo, que operações em ambientes de produção sempre passem por revisão humana, mesmo em pipelines automatizados.
Conclusão: pequenas releases, grandes responsabilidades
A v2.1.211 do Claude Code é um microcosmo do que significa maturar uma ferramenta de agentes para uso profissional sério. Não há novos modelos, não há features chamativos no README — mas há três correções que tocam diretamente em três pilares fundamentais: ver o que está acontecendo (observabilidade dos subagentes), confiar no que está sendo aprovado (segurança dos previews) e manter o controle quando você quer ter controle (integridade dos hooks).
Se você usa Claude Code em produção, em pipelines multiagente ou em ambientes que processam dados externos, essa atualização não é opcional — é manutenção necessária.
Atualize, revise seus hooks, e se ainda não usa stream-json com pipelines multiagente, esse é um bom momento para começar.
Ficou com dúvidas sobre como configurar hooks PreToolUse ou como estruturar um pipeline de observabilidade com Claude Code? Deixa nos comentários — a pauta do próximo post pode ser a sua pergunta.
