6. 제어 이벤트 (control.*)
마스터 서버가 클라이언트(에이전트)로 전달하는 제어 명령이다.
6.1. 프롬프트/입력 전달
6.1.1. control.prompt.request (Master → Client)
{
"type": "control.prompt.request",
"payload": {
"prompt_text": "String (필수, 사용자 입력. 파일 참조 토큰 포함 가능, §16.2 참조)",
"input_type": "String (선택, 기본값 'text'. 아래 열거 값)",
"context_files": [
{
"file_url": "String (필수, 참조 파일 URL)",
"file_name": "String (필수)",
"mime_type": "String (선택)",
"intent": "String (선택, 'reference' | 'edit_target' | 'context')"
}
],
"file_references": [
{
"ref_id": "String (필수, prompt_text 내 토큰의 ref_id와 일치)",
"path": "String (필수, workspace 기준 상대 경로)",
"name": "String (필수, 파일명)",
"extension": "String (선택, 확장자)",
"mime_type": "String (선택, IANA MIME 타입)",
"size_bytes": "Number (선택)",
"workspace_relative_path": "String (필수, 워크스페이스 기준 상대 경로)"
}
],
"config_overrides": {
"output_format": "String (선택, 'text' | 'json' | 'stream-json')",
"json_schema": "Object (선택, 구조화 출력 스키마)",
"max_turns": "Number (선택, 최대 Turn 수 제한)",
"allowed_tools": ["String (선택, 허용 도구 목록)"],
"denied_tools": ["String (선택, 금지 도구 목록)"]
}
}
}변경 사항:
file_references필드가 추가되었다. 이 필드는prompt_text내에 삽입된 인라인 파일 참조 토큰(§16.2)의 메타데이터를 제공한다.file_references와 기존context_files의 관계:context_files는 프롬프트와 함께 첨부되는 참조 파일이고,file_references는 프롬프트 텍스트 내에서 인라인으로 언급된 파일의 메타데이터이다. 양자는 독립적이며, 동일 파일이 양쪽에 모두 존재할 수 있다.
input_type 열거 값:
| 값 | 설명 |
|---|---|
text |
일반 텍스트 프롬프트 |
slash_command |
슬래시 명령 (예: /compact, /cost) |
continuation |
이전 Turn에 이어지는 후속 입력 |
piped_stdin |
파이프된 표준 입력 (headless 모드) |
6.1.2. control.prompt.cancel (Master → Client)
진행 중인 에이전트 Turn을 취소한다. 수신 시 클라이언트는 현재 실행 중인 도구를 가능한 한 빨리 중단하고, agent.text.done(is_cancelled: true)을 발송해야 한다 (MUST).
{
"type": "control.prompt.cancel",
"payload": {
"target_turn_id": "String (필수, 취소 대상 turn_id)",
"reason": "String (선택, 'user_cancelled' | 'timeout' | 'quota_exceeded')"
}
}6.2. 상호작용 응답
6.2.1. control.interaction.response (Master → Client)
{
"type": "control.interaction.response",
"payload": {
"interaction_id": "String (필수, 대응하는 agent.interaction.request의 interaction_id)",
"selected_value": "String | [String] (필수, 단일 선택 또는 복수 선택 값)",
"text_input": "String (선택, TEXT_INPUT 타입의 사용자 자유 입력)"
}
}6.2.2. control.interaction.timeout (Master → Client)
{
"type": "control.interaction.timeout",
"payload": {
"interaction_id": "String (필수)"
}
}6.3. 세션 제어 명령
6.3.1. control.session.compact (Master → Client)
마스터가 컨텍스트 압축을 요청한다 (사용자의 /compact 명령 등).
{
"type": "control.session.compact",
"payload": {
"instruction": "String (선택, 압축 시 보존할 내용 지시)",
"target_token_ratio": "Number (선택, 0.0–1.0, 목표 압축 비율)"
}
}6.3.2. control.mode.switch (Master → Client)
에이전트 동작 모드를 전환한다.
{
"type": "control.mode.switch",
"payload": {
"mode": "String (필수, 아래 열거 값)",
"config": "Object (선택, 모드별 추가 설정)"
}
}mode 열거 값:
| 값 | 설명 |
|---|---|
default |
기본 실행 모드 (읽기/쓰기/실행 모두 가능) |
plan |
계획 모드 (읽기/검색만 허용, 쓰기/실행 차단) |
review |
코드 리뷰 모드 |