Mensagens entre sessões no Claude Code

Desde a v2.1.224, toda sessão interativa do Claude Code em uma máquina Mac ou Linux abre um socket Unix no instante em que começa (o meu fica em /tmp/cc-socks/38590.sock, com permissões restritas ao dono), e qualquer outra sessão que você tenha rodando pode depositar ali uma mensagem de texto.¹ Duas ferramentas movem o recurso: ListAgents descobre quais das suas sessões estão acessíveis, e SendMessage entrega a uma delas pelo nome.² Nada para ativar, nada para configurar. Se as duas sessões rodam a v2.1.224 ou posterior na mesma máquina, elas já conseguem conversar.

TL;DR

As sessões do Claude Code agora podem trocar mensagens entre si: dentro de uma máquina, por sockets locais que nunca passam pelos servidores da Anthropic, e entre máquinas, pelo Remote Control – só respostas no lançamento, e a v2.1.225 acrescentou a capacidade de iniciar essas conversas pelo nome.¹⁵ A mensagem é texto puro, nunca histórico de conversa, arquivos ou permissões, e a sessão que recebe trata aquilo como entrada, não como autoridade: ela não aprova prompts, não muda configuração e não executa comandos.¹ O recurso transforma uma frota de terminais independentes em algo mais próximo de um time, e os melhores usos são as mensagens de coordenação que você antes carregava na mão: “a migração terminou”, “renomeei aquela coluna”, “pode fazer rebase na main sem medo”. A pior armadilha é a ausência silenciosa: quatro variáveis de ambiente de privacidade, sem relação entre si, desligam o recurso sem avisar.³

O que foi lançado

A versão v2.1.224 trouxe o SendMessage entre sessões, com descoberta via ListAgents, no macOS e no Linux; a v2.1.225 estendeu o recurso para que uma sessão também consiga iniciar uma conversa com suas sessões de Remote Control em outras máquinas – antes, ela só conseguia responder.⁴⁵

Três superfícies deixam a engrenagem à vista:

• /list-agents (apelido /peers) lista todas as sessões que o Claude alcança: subagentes dentro da sessão atual, suas outras sessões locais, incluindo as que rodam em segundo plano, e, enquanto o Remote Control estiver conectado, suas sessões em outras máquinas e no Claude Code na web.¹
• /status exibe uma linha Peer address com o socket de entrada da própria sessão, prefixado por uds:.¹
• CLAUDE_CODE_MESSAGING_SOCKET é exportada para todo gancho e comando Bash, contendo o caminho do socket da própria sessão.⁶ Falo mais sobre por que isso importa adiante.

Verificando na minha própria máquina: uma sessão rodando a v2.1.226 lista duas sessões vizinhas com o estado (“busy”) e o tempo de vida de cada uma, e o arquivo de socket carrega permissões srw-------: leitura e escrita apenas para o meu usuário, que é a fronteira em máquinas compartilhadas.¹

As sessões atendem por nome. Você define um com /rename ou com a flag --name; caso contrário, o Claude Code deriva um do diretório de trabalho, algo como myapp-3f.¹ Quando duas sessões colidem no mesmo nome, a listagem as diferencia pelo diretório de trabalho e por um identificador curto.¹

O modelo de confiança é a parte interessante

O desenho da Anthropic responde a uma pergunta em que a maioria dos sistemas multiagente tropeça: quanto vale uma mensagem vinda de outro agente? Aqui a resposta é precisa: mensagem é informação, nunca autoridade.¹

Quando a sessão A manda mensagem para a sessão B, quatro regras limitam o que chega:¹

1. Ela não aprova nada. Um prompt de permissão pendente em B ignora qualquer coisa que A diga. Só você responde prompts.
2. Ela não muda configuração. O Claude que recebe é instruído a nunca alterar configurações de permissão, o CLAUDE.md ou qualquer configuração porque outra sessão pediu.
3. Comandos chegam como texto. Um /compact no corpo da mensagem é só texto, nunca um comando executado.
4. Os prompts de permissão continuam aparecendo. Se agir sobre a mensagem exigir uma permissão que B não tem, você vê o mesmo prompt de qualquer outro trabalho.

A entrega de mensagens recebidas tem a própria barreira. Cada mensagem que chega termina em um de três resultados – entregue, retida para sua aprovação ou recusada –, controlados pela configuração crossSessionInbound (accept, hold, refuse).¹ Se você não configurar nada, o Claude Code decide mensagem a mensagem com base nos modos de permissão das duas sessões, e a lógica padrão é elegante: as sessões que pulam os prompts de permissão formam uma classe; todas as demais, a outra. Uma sessão que pergunta recebe mensagens livremente, mas retém tudo que vem de uma sessão que pula os prompts; uma sessão que pula retém tudo, exceto mensagens de outras sessões que também pulam.¹ A assimetria é deliberada: uma mensagem não pode pegar carona na autoridade de uma sessão permissiva – princípio que a v2.1.224 aplica na entrada depois de a v2.1.222 tê-lo aplicado na saída no modo auto, onde o classificador de permissões revisa cada envio antes do despacho.⁷

Mensagens retidas abrem uma caixa de diálogo de aprovação com remetente e prévia; diálogos sem resposta expiram em cinco minutos (ajustável por dialogExpiry) e a mensagem é descartada.¹ No máximo 100 mensagens ficam retidas ao mesmo tempo.¹ Mais dois controles apertam o cerco: isolatePeerMachines: true exige sua aprovação explícita antes de qualquer mensagem sair da máquina, mesmo no modo bypassPermissions, e um true vindo de qualquer escopo de configuração prevalece – ou seja, um arquivo de projeto versionado pode apertar, nunca afrouxar.¹ Organizações podem matar o recurso de vez com regras de negação em SendMessage e ListAgents, mais crossSessionInbound: "refuse" nas configurações gerenciadas.¹

Como as mensagens viajam

Onde a outra sessão roda determina tanto o transporte quanto o que você pode enviar:¹

Vale sinalizar um conflito na documentação: até a redação deste texto, a página da Anthropic sobre mensagens entre sessões ainda descreve toda troca entre máquinas como exclusiva de respostas, enquanto as notas de versão da v2.1.225 dizem que o SendMessage “agora pode iniciar uma conversa, pelo nome, com suas sessões de Remote Control em outras máquinas”. As notas de versão são mais recentes; a página de documentação está atrasada em relação ao lançamento.¹⁵

A regra do “mesma máquina” é visibilidade de sistema de arquivos: as sessões se registram em arquivos no disco, então duas sessões só se alcançam quando enxergam os mesmos arquivos. Uma sessão dentro de um container e outra no host não conversam; duas sessões dentro do mesmo container, sim.¹

A entrega respeita o ritmo da sessão que recebe: a mensagem é lida entre chamadas de ferramenta durante um turno ativo, sem nunca interromper uma ferramenta em execução, e abre um turno novo quando a sessão está ociosa.¹ Mensagens entregues contam no consumo como um prompt que você mesmo tivesse digitado.¹

Cinco padrões que valem a pena construir

1. Coordenação entre worktrees. O caso óbvio, e o que a documentação ilustra com um exemplo próprio de mensagem: sessões trabalhando no mesmo repositório em worktrees separadas contam umas às outras o que entrou.¹ “A migração de schema terminou: a nova coluna é tenant_id, e agora dá para fazer rebase na main com segurança.” é a mensagem de exemplo da própria documentação – o tipo de atualização que, sem isso, depende de você perceber, trocar de terminal e redigitar. Se várias sessões compartilham um único checkout em vez de worktrees, a mensagem de coordenação fica ainda mais valiosa: “vou commitar content/guides/ agora, não coloque isso no stage” evita a colisão clássica da árvore compartilhada, em que uma sessão commita o trabalho pela metade de outra.

2. Observador e executor. Rode uma sessão de monitoramento acompanhando um deploy, uma suíte de testes ou um log, e faça com que ela avise a sessão responsável pelas correções no instante em que algo quebra. A sessão que recebe ganha o achado como contexto, não como ordem; ela ainda decide, dentro das próprias permissões, o que fazer. Combine isso com sessões em segundo plano e com os ganchos de notificação e você tem uma cadeia de escalonamento que só chega a um humano quando deve.

3. O processo longo que se reporta. Dispare uma migração ou uma rodada demorada de testes em uma sessão e peça que ela dê retorno à sessão que você de fato acompanha.¹ O status deixa de morar num terminal que você esqueceu. O inverso também funciona; basta perguntar do lado de quem observa: “pergunte à sessão do meu outro terminal se a migração terminou” é um prompt como outro qualquer, e o próprio Claude cuida da descoberta, do endereçamento e da redação.¹

4. Frotas de workers sem supervisão. Sessões headless com claude -p também abrem sockets de entrada, então um worker -p de longa duração recebe mensagens e aparece nas listagens.⁸ O detalhe: uma sessão -p não consegue exibir a caixa de aprovação, então uma mensagem retida fica retida, sem caminho para a entrega a não ser mudar configuração ou modo (a v2.1.225 também corrigiu o caso em que essas mensagens ficavam estacionadas sem aviso nem expiração). Para rodar um worker que aceita mensagens sem supervisão, inicie-o com crossSessionInbound: "accept" no valor de --settings: uma permissão por worker, em vez de um accept nas configurações de usuário, que valeria para toda sessão que você abrir.⁸ Sessões em modo bare pulam o socket por completo e ficam inalcançáveis.⁸

5. Caixas de entrada por script. A potência silenciosa: como CLAUDE_CODE_MESSAGING_SOCKET é exportada para ganchos e comandos Bash, um script consegue postar na caixa de entrada da própria sessão.⁶ O Claude Code verifica mensagens de processos filhos: um gancho ou comando que responde à própria sessão entrega sem cerimônia quando não há crossSessionInbound explícito.¹ Uma rotina noturna, um gancho do Git, um wrapper de CI: qualquer coisa capaz de escrever em um socket Unix agora consegue injetar uma linha de contexto na sessão que a criou. No Linux, a verificação funciona mesmo depois que o processo que postou termina; no macOS, só enquanto ele ainda roda; em um container onde o Claude Code é o PID 1, a verificação falha e a mensagem volta às regras normais de entrada.¹ Comandos em ambiente isolado precisam que o socket seja liberado via sandbox.network.allowUnixSockets.¹

O que ele se recusa a ser

Os limites são decisões de projeto, e respeitá-los evita que você construa a coisa errada.

Não é um canal de aprovação. Tudo no modelo de confiança existe para impedir que uma sessão autorize as ações de outra. Qualquer fluxo de trabalho no formato “a sessão A aprova, a sessão B executa” foi explicitamente desenhado para não funcionar. A autoridade passa sempre pelo humano.¹

Não é transferência de contexto. A mensagem é um texto que um Claude escreve para outro, nunca histórico de conversa nem arquivos. A documentação da Anthropic diz sem rodeios: para mover uma conversa, retome a sessão.¹ Resuma; não despeje.

Não é agent teams. Sessões independentes trocando mensagens é o caso ponto a ponto. Um time coordenado que o Claude cria e supervisiona (mensagens de protocolo estruturadas, uma lista de integrantes, estado de tarefas compartilhado) é o recurso de agent teams, e as mensagens estruturadas de time ficam deliberadamente dentro do time.¹ Se você se pegar projetando um protocolo de mensagens em cima do texto entre sessões, o que você quer é agent teams.

Não é um chat em loop. O Claude Code limita a taxa de mensagens repetidas por remetente, descarta repetições idênticas que chegam em uma janela curta e trava em 50 por sessão as mensagens aceitas e não lidas – ou seja, um loop de mensagens entre duas sessões se esgota sozinho, por projeto.¹ Construa trocas de pergunta e resposta, não conversas.

As armadilhas

Variáveis de privacidade desligam tudo em silêncio. As mensagens entre sessões dependem da avaliação de feature flags, e qualquer uma entre CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK e DISABLE_GROWTHBOOK desliga essa avaliação e leva a troca de mensagens junto, sem avisar.³ O diagnóstico é o /list-agents: se o comando nem sequer é reconhecido, a sessão não tem o recurso; se ele funciona mas o envio nunca chega, o problema é mais específico – uma regra de negação, os controles de entrada de quem recebe ou um destino em outra máquina que só aceita respostas.¹

Lacunas de plataforma e de provedor. Não há suporte nativo no Windows (o Linux dentro do WSL 2 funciona). Não está disponível no Amazon Bedrock, no Claude Platform na AWS, no Agent Platform do Google Cloud nem no Microsoft Foundry.¹

O caso da resposta de mão única. Uma resposta enviada a uma sessão em outra máquina, enquanto a sessão que responde não está conectada ao Remote Control, chega mesmo assim – só que sem endereço de retorno, então quem recebe não consegue responder. O Claude é avisado disso no momento do envio, e as correções da v2.1.225 apertaram o endereçamento para que um destinatário confirmado em outra máquina nunca seja trocado, em silêncio, por uma sessão local de mesmo nome.⁵

Retenções em modo headless. O worker -p que misteriosamente ignora mensagens é quase sempre um caso de mensagem retida: sem diálogo, sem entrega. Defina crossSessionInbound: "accept" nos workers que devem escutar.⁸

Principais conclusões

Para quem usa o Claude Code todo dia: - Rode /list-agents uma vez para ver o que suas sessões já alcançam; nomeie as sessões importantes com /rename para que as mensagens sejam endereçadas sem ambiguidade. - Peça as mensagens em linguagem natural (“avise a sessão que está mexendo em pagamentos sobre o que mudamos”) e deixe o próprio Claude redigir o texto.¹

Para quem constrói automações: - Poste em sessões a partir de ganchos e scripts via CLAUDE_CODE_MESSAGING_SOCKET; no Linux, mensagens de processos filhos são entregues sem atrito de aprovação.¹⁶ - Dê aos workers -p sem supervisão o crossSessionInbound: "accept" no --settings deles, não globalmente.⁸

Para times e revisores de segurança: - O recurso sai com os padrões certos: mensagens não carregam autoridade, sessões que pulam permissões ficam em quarentena por padrão, e isolatePeerMachines mais as regras de negação nas configurações gerenciadas dão a você chaves de desligamento por máquina e para a organização inteira.¹ - Audite as quatro variáveis de ambiente de privacidade antes de concluir que a troca de mensagens está quebrada, e saiba que uma sessão em modo de recusa não apresenta nenhuma diferença visível para as vizinhas.¹

Referências