RAWP-DPS 1.0.0

1.0.0 ko public

5. 도구 호출 이벤트 (`tool.*`)

에이전트가 도구(Tool)를 호출하고 그 결과를 보고하는 이벤트 군이다. Claude Code의 Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS, WebFetch, WebSearch, NotebookRead, NotebookEdit, TodoRead, TodoWrite, Task(Subagent) 등 모든 도구 호출을 통일된 구조로 표현한다.

5.1. 설계 원칙

도구 호출 이벤트는 도구 비종속(Tool-Agnostic) 설계를 따른다. 즉, 프로토콜은 도구의 이름, 입력 스키마, 출력 형태를 사전에 정의하지 않으며, 임의의 도구를 동일한 Envelope으로 수용한다. 도구별 의미론은 tool_name과 input/output 필드의 내용으로 결정된다.

5.2. 도구 호출 요청

5.2.1. `tool.invoke.request` (Client → Master)

에이전트가 도구를 호출하려 함을 마스터에 통보한다. 승인이 필요한 도구의 경우 agent.interaction.request가 선행한다.

{
  "type": "tool.invoke.request",
  "payload": {
    "invocation_id": "String (필수, UUID v4, 이 호출의 고유 식별자)",
    "tool_name": "String (필수, 도구명. 예: 'Bash', 'Read', 'Edit', 'TodoWrite')",
    "tool_version": "String (선택, 도구 버전)",
    "input": "Object (필수, 도구별 입력 파라미터)",
    "parallel_group_id": "String (선택, 병렬 호출 그룹 ID. 동시에 발송되는 도구 호출을 그룹화)"
  }
}

5.3. 도구 실행 결과

5.3.1. `tool.invoke.result` (Client → Master)

도구 실행이 완료된 후 결과를 보고한다.

{
  "type": "tool.invoke.result",
  "payload": {
    "invocation_id": "String (필수, 대응하는 tool.invoke.request의 invocation_id)",
    "tool_name": "String (필수)",
    "status": "String (필수, 'success' | 'error' | 'timeout' | 'cancelled')",
    "output": "Any (필수, 도구별 출력. 구조는 도구 의존적)",
    "output_type": "String (필수, 출력 해석 힌트. 아래 열거 값)",
    "duration_ms": "Number (선택, 실행 소요 시간 밀리초)",
    "truncated": "Boolean (선택, 출력이 잘렸는지 여부)"
  }
}

output_type 열거 값:

값	설명	대표 도구
`text`	평문 텍스트	Bash stdout, Grep 결과
`structured`	JSON 구조체	TodoRead, Agent Discovery
`file_content`	파일 본문 (라인 번호 포함 가능)	Read, NotebookRead
`file_list`	파일 경로 목록	Glob, LS
`diff`	변경사항 차분 (unified diff 또는 구조화 diff)	Edit, MultiEdit 결과
`web_content`	웹 페이지/검색 결과	WebFetch, WebSearch
`empty`	출력 없음 (부수효과만 발생)	Write, NotebookEdit
`binary_ref`	바이너리 참조 (agent.file.transfer 연계)	이미지 생성 등
`agent_result`	서브에이전트 실행 결과	Task(Subagent)

5.3.2. `tool.invoke.stream` (Client → Master)

장시간 실행 도구의 중간 출력을 스트리밍한다 (예: Bash 명령의 실시간 stdout).

{
  "type": "tool.invoke.stream",
  "payload": {
    "invocation_id": "String (필수)",
    "tool_name": "String (필수)",
    "stream_type": "String (필수, 'stdout' | 'stderr' | 'progress')",
    "chunk": "String (필수, 출력 조각)",
    "sequence": "Number (필수, 0-based 순번, 순서 재구성용)"
  }
}

5.4. 도구 사용 가능 목록 고지 (Tool Catalog)

5.4.1. `tool.catalog.publish` (Client → Master)

에이전트가 현재 세션에서 사용 가능한 도구 목록을 마스터에 고지한다. 세션 시작 직후 또는 도구 구성 변경 시 발송한다.

{
  "type": "tool.catalog.publish",
  "payload": {
    "tools": [
      {
        "name": "String (필수, 도구명)",
        "version": "String (선택)",
        "description": "String (필수, 도구 설명)",
        "input_schema": "Object (선택, JSON Schema)",
        "output_type": "String (선택, 기본 output_type)",
        "requires_approval": "Boolean (선택, 실행 전 승인 필요 여부)",
        "category": "String (선택, 도구 분류. 아래 열거 값)"
      }
    ]
  }
}

category 열거 값:

값	설명	예시
`filesystem`	파일 시스템 조작	Read, Write, Edit, MultiEdit, Glob, LS
`shell`	셸 명령 실행	Bash
`search`	검색	Grep, WebSearch
`web`	웹 콘텐츠 접근	WebFetch
`notebook`	노트북 조작	NotebookRead, NotebookEdit
`task_management`	태스크/TODO 관리	TodoRead, TodoWrite
`agent`	서브에이전트 위임	Task
`planning`	계획 모드	EnterPlanMode, ExitPlanMode
`mcp`	MCP 서버 도구	동적 MCP 도구
`custom`	사용자 정의 도구	커스텀 도구

참조

RAWP v1.0.0

5. 도구 호출 이벤트 (tool.*)

5.1. 설계 원칙

5.2. 도구 호출 요청

5.2.1. tool.invoke.request (Client → Master)