Claude Code 교차 세션 메시징: 작동 방식, 사용 시점 및 보안 고려 사항

TL;DR

Claude Code는 활성 세션 중 하나에서 다른 세션으로 일반 텍스트 메시지를 자동으로 보낼 수 있어, 수동으로 복사하여 붙여넣지 않고도 세션 간에 중대한 변경 사항을 경고하거나, 상태 업데이트를 공유하거나, 차단된 질문에 답할 수 있습니다. 이 기능은 세션별 인바운드 제어 및 권한 모드를 준수하며, 완전히 제한하거나 비활성화할 수 있습니다.

교차 세션 메시징이란 무엇인가

교차 세션 메시징은 Claude 인스턴스가 사용자가 소유한 다른 Claude 세션에 텍스트 메시지를 전달할 수 있도록 하는 Claude Code의 내장 기능입니다. 이는 대화 기록, 파일 또는 구조화된 데이터를 전송하는 것이 아니라 오직 메시지 텍스트만 전송합니다.

내부적으로 사용되는 도구: ListAgents (도달 가능한 에이전트 검색) 및 SendMessage (메시지 전달). 사용자는 이 도구들을 직접 호출하지 않습니다.
범위: 동일한 머신 내의 독립적인 세션 간, Remote Control를 통한 머신 간, 또는 웹 기반 Claude Code 세션 간에 작동합니다. 원격 세션에서 새로운 대화를 시작할 수는 없으며, 들어오는 메시지에 답장할 수만 있습니다.

언제 사용해야 하는가

세션이 작업 도중 다른 세션에 필요한 정보를 알게 되었을 때 메시징을 사용하십시오. 일반적인 패턴은 다음과 같습니다:

사용 사례	메시징의 도움
발견 사항 전달	한 세션이 중대한 변경 사항을 발견하면; Claude가 이를 요약하여 관련 세션에 전송하여 수동 재설명을 방지합니다.
병렬 워크트리 조정	여러 세션이 동일한 저장소의 서로 다른 워크트리에서 작동할 때; Claude가 서로에게 반영된 변경 사항을 알립니다.
장시간 실행되는 작업의 상태 확인	마이그레이션 또는 테스트 실행이 모니터링 세션에 진행 상황을 보고할 수 있습니다.
머신 간 답장	노트북의 세션이 데스크톱 세션에서 도착한 메시지에 답장할 수 있습니다.

세션을 재개하거나, 조정된 에이전트 팀을 실행하거나, 많은 세션을 관찰하거나, 세션을 원격으로 제어하거나, 외부 이벤트를 푸시해야 하는 경우, Claude Code는 이미 전용 기능(resume, agent teams, agent view, Remote Control, channels)을 제공합니다. 교차 세션 메시징은 위의 시나리오에 대해서만 사용하십시오.

메시지 전송 및 전달 방식

탐색(Discovery) – Claude가 ListAgents를 호출하여 도달 가능한 세션을 찾습니다.
전송(Sending) – Claude가 대상의 이름과 메시지 텍스트를 사용하여 SendMessage를 호출합니다.
전달(Delivery) – 수신 세션은 현재 턴 중에 메시지를 처리하거나, 유휴 상태인 경우 새로운 턴을 시작합니다.
결과(Outcome) – 인바운드 제어에 따라 메시지가 전달(Delivered), 보류(Held) 또는 거부(Refused) 여부가 결정됩니다.

Delivered 메시지는 수신되는 Claude에게 전달되며 일반 프롬프트와 같이 사용량에 포함됩니다. Held 메시지는 사용자가 승인할 때까지(또는 설정이 변경될 때까지) 대기열에 머뭅니다. Refused 메시지는 조용히 드롭됩니다.

인바운드 제어 (`crossSessionInbound`)

crossSessionInbound 설정은 들어오는 메시지의 기본 처리 방식을 결정합니다:

값	동작
`accept`	모든 메시지가 전달됩니다.
`hold`	각 메시지가 알림을 트리거하며, 전달 전에 승인해야 합니다.
`refuse`	메시지가 전달되지 않고 드롭됩니다.

명시적인 값이 적용되지 않으면 Claude는 권한 모드 클래스로 대체됩니다:

권한 프롬프트를 건너뛰는 세션(예: auto, acceptEdits)은 송신자도 건너뛰지 않는 한 들어오는 메시지가 **보류(held)**됩니다.
권한을 요청하는 세션은 메시지를 즉시 전달합니다.

보류된 메시지가 승인되면 전달되지만, 만료되거나(기본 5분) 거부하면 드롭됩니다. 세션은 최대 100개의 메시지를 보류할 수 있으며, 오래된 메시지는 폐기됩니다.

머신 간 메시징 제한

대상	전송 방식	전송 가능 내용
동일 머신	Direct Unix-domain socket	새 메시지 및 답장
다른 머신 (Remote Control)	Anthropic servers → Remote Control	답장만 가능
웹의 Claude Code	Anthropic servers	답장만 가능

원격 머신으로 보내는 메시지는 답장 전용입니다. 세션이 원격 피어와 새로운 교환을 시작할 수 없습니다. 호스트를 떠나기 전 모든 교차 머신 메시지에 대해 명시적 승인을 요구하려면 isolatePeerMachines=true로 설정하십시오.

보안 및 권한 모델

묵시적 동의 없음 – 들어오는 메시지는 사용자의 승인으로 간주되지 않습니다. 메시지는 권한 프롬프트를 승인하거나, 구성 파일을 변경하거나, 텍스트에 포함된 명령을 실행할 수 없습니다.
권한 프롬프트는 여전히 발생함 – 메시지에 따라 동작하는 데 수신 세션에 없는 권한이 필요한 경우, 다른 작업과 동일한 프롬프트가 표시됩니다.
도구 거부 – 관리자는 권한 규칙에서 SendMessage 및 ListAgents 도구를 거부함으로써 메시징을 완전히 차단할 수 있습니다.
잠재적 공격 표면 – Hacker News 댓글 작성자가 언급했듯이, 메시징 채널을 노출하면 설정 오류 시 원격 코드 실행(RCE)의 벡터가 될 수 있습니다. 적절한 인바운드 제어(crossSessionInbound=hold 또는 refuse) 및 isolatePeerMachines가 이 위험을 완화합니다.

세션 및 이름 관리

/list-agents (또는 /peers)를 사용하여 도달 가능한 세션과 그 이름을 확인할 수 있습니다.
세션은 /rename 또는 --name CLI 플래그로 설정된 이름으로 호출됩니다. 이름이 충돌하면 Claude가 구분을 위해 짧은 식별자를 추가합니다.
인박스 소켓을 바인딩한 세션만 목록에 나타납니다. bare mode의 헤드리스 claude -p 세션은 소켓을 바인딩하지 않으므로 메시지를 수신할 수 없습니다.
인박스 소켓 경로는 CLAUDE_CODE_MESSAGING_SOCKET을 통해 노출되며 /status의 Peer address 아래에 표시됩니다.

커뮤니티의 실용적인 팁

"저는 tmux, 메모리 트리, 핸드오프 파일을 사용하여 이것을 직접 만들었습니다. 중복 컨텍스트를 최소화하고 토큰 비용을 절약할 수 있었습니다." – eigenblake

"저는 Tailscale를 통해 Linux 머신 군단 전체에서 다른 모델에게 메시지를 보내도록 Claude를 스크립트화했습니다. 잘 작동하지만 때때로 루프를 멈추기 위한 수동 개입이 필요합니다." – Cyuonut

"이 기능을 사용해 보니 'hold swarm, I prepare safe exfil'과 같은 메시지를 보았습니다. 시스템은 반복되는 메시지를 조절하고 세션당 대기 중인 메시지를 50개로 제한하여 무한 루프를 방지합니다." – dist-epoch

이러한 일화들은 내장된 도구가 Claude의 권한 시스템과 더 긴밀하게 통합되어 있으면서도 사용자 정의 오케스트레이션(tmux, IRC, HTTP hooks)에 필적함을 확인시켜 줍니다.

메시징을 끄는 방법

수신 중단 – 사용자, 프로젝트 또는 관리 설정에서 crossSessionInbound=refuse로 설정합니다.
송신/목록 표시 중단 – SendMessage 및 ListAgents에 대한 권한 거부 규칙을 추가합니다.
조직 전체 비활성화 – 관리 설정에서 두 가지 접근 방식을 결합하여 어떤 세션도 메시지를 보내거나 받을 수 없도록 보장할 수 있습니다.

비활성화된 상태에서도 각 세션은 여전히 인박스 소켓을 바인딩하며, 메시지는 가시적인 부작용 없이 단순히 드롭됩니다.

가용성 및 요구 사항

버전 – Claude Code v2.1.224 이상이 필요합니다.
OS – macOS 및 Linux(WSL 2 포함)에서 지원됩니다. 네이티브 Windows에서는 사용할 수 없습니다.
제공업체 – Amazon Bedrock, AWS의 Claude Platform, Google Cloud Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다.
기능 플래그 – 환경 변수 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK 또는 DISABLE_GROWTHBOOK 중 하나라도 기본 플래그를 끄는 값으로 설정되어 있으면 기능이 비활성화됩니다.

/list-agents (또는 /peers)로 세션을 확인하십시오. 명령어를 인식할 수 없다면 해당 세션에 필요한 버전이나 기능 플래그가 없는 것입니다.

제한 사항

일반 텍스트 메시지만 지원됩니다. 구조화된 팀 프로토콜은 에이전트 팀 내에서만 유지됩니다.
메시지 루프는 조절됩니다: 짧은 시간 내의 동일한 반복은 드롭되며, 세션은 대기 중인 메시지를 50개로 제한합니다.
컨테이너는 격리된 파일 시스템을 가집니다. 컨테이너 내부의 세션은 동일한 소켓 디렉토리를 공유하지 않는 한 호스트 세션에 도달할 수 없습니다.

요약

Claude Code의 교차 세션 메시징은 독립적인 Claude 세션이 수동으로 복사하여 붙여넣지 않고도 작업을 조정하고, 발견 사항을 공유하고, 상태를 보고할 수 있는 가볍고 권한을 인식하는 방법을 제공합니다. 인바운드 제어, 격리 플래그 및 권한 규칙을 구성함으로써 사용자는 편의성과 보안 사이의 균형을 맞출 수 있습니다.