제어 프로토콜

제어 프로토콜 개요

제어 프로토콜은 호스트 애플리케이션과 Claude Code CLI 간의 구조화된 통신 방식입니다. 일반 사용자 메시지와 별도로, 세션 초기화, 모델 변경, 권한 처리 등 시스템 수준 작업을 처리합니다.

Host → CLI: SDKControlRequest  (제어 명령)
CLI  → Host: SDKControlResponse (제어 응답)
Host → CLI: SDKUserMessage     (사용자 메시지)
CLI  → Host: can_use_tool      (권한 요청)

SDKControlRequest (Host → CLI)

호스트에서 CLI로 전송하는 제어 요청입니다.

작업 (subtype)	방향	설명
initialize	Host → CLI	세션 초기화, 시스템 프롬프트 설정
interrupt	Host → CLI	현재 실행 중인 작업 중단
set_model	Host → CLI	사용 모델 변경
set_permission_mode	Host → CLI	권한 모드 변경
mcp_status	Host → CLI	MCP 서버 상태 조회
mcp_set_servers	Host → CLI	MCP 서버 목록 동적 설정
get_context_usage	Host → CLI	컨텍스트 윈도우 사용량 조회
rewind_files	Host → CLI	파일 변경 사항 롤백

// initialize 요청 예시
{
  "type": "control",
  "subtype": "initialize",
  "systemPrompt": "당신은 TypeScript 전문가입니다.",
  "appendSystemPrompt": "항상 한국어로 응답하세요.",
  "permissionMode": "auto-edit"
}

// set_model 요청 예시
{
  "type": "control",
  "subtype": "set_model",
  "model": "claude-opus-4-5"
}

SDKControlResponse (CLI → Host)

CLI에서 호스트로 반환하는 제어 응답입니다.

// initialize 응답 예시
{
  "type": "control_response",
  "subtype": "initialize",
  "capabilities": ["streaming", "tools", "vision", "mcp"],
  "model": "claude-sonnet-4-5",
  "agents": [
    {
      "name": "code-reviewer",
      "description": "코드 품질 리뷰 에이전트",
      "model": "claude-haiku-4-5"
    }
  ],
  "account": {
    "email": "user@example.com",
    "tier": "pro"
  },
  "apiProvider": "firstParty"
}

필드	설명
capabilities	지원하는 기능 목록
model	현재 사용 중인 모델
agents	정의된 커스텀 에이전트 목록
account	계정 정보
apiProvider	현재 API 프로바이더

can_use_tool (CLI → Host)

Claude가 도구를 실행하기 전에 호스트에 권한을 요청하는 메시지입니다.

// CLI → Host: 권한 요청
{
  "type": "can_use_tool",
  "tool": "Bash",
  "input": { "command": "rm -rf ./dist" },
  "request_id": "req-abc123"
}

// Host → CLI: 권한 응답
{
  "type": "tool_permission_response",
  "request_id": "req-abc123",
  "granted": true,
  "remember": false
}

호스트는 이 메시지를 처리하여 사용자에게 확인 UI를 표시하거나, 정책 기반으로 자동 승인/거부할 수 있습니다.

SDKUserMessage

호스트에서 CLI로 전송하는 사용자 메시지입니다.

// 기본 사용자 메시지
{
  "type": "user",
  "message": {
    "role": "user",
    "content": "인증 모듈을 리팩토링해 주세요"
  }
}

// 도구 응답에 연결된 메시지
{
  "type": "user",
  "message": {
    "role": "user",
    "content": "계속 진행해 주세요"
  },
  "parent_tool_use_id": "toolu_xyz789"
}

parent_tool_use_id를 사용하면 특정 도구 호출의 결과에 이어지는 메시지를 전송할 수 있어 복잡한 멀티턴 대화 흐름을 정밀하게 제어할 수 있습니다.