517 async def set_model(self, model: str | None = None) -> None517 async def set_model(self, model: str | None = None) -> None
518 async def rewind_files(self, user_message_id: str) -> None518 async def rewind_files(self, user_message_id: str) -> None
519 async def get_mcp_status(self) -> McpStatusResponse519 async def get_mcp_status(self) -> McpStatusResponse
520 async def get_context_usage(self) -> ContextUsageResponse
520 async def reconnect_mcp_server(self, server_name: str) -> None521 async def reconnect_mcp_server(self, server_name: str) -> None
521 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None522 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
522 async def stop_task(self, task_id: str) -> None523 async def stop_task(self, task_id: str) -> None
540| `set_model(model)` | 현재 세션의 모델 변경. [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정하려면 `None` 전달 |541| `set_model(model)` | 현재 세션의 모델 변경. [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정하려면 `None` 전달 |
541| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |542| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |
542| `get_mcp_status()` | 구성된 모든 MCP 서버의 상태 가져오기. [`McpStatusResponse`](#mcpstatusresponse) 반환 |543| `get_mcp_status()` | 구성된 모든 MCP 서버의 상태 가져오기. [`McpStatusResponse`](#mcpstatusresponse) 반환 |
544| `get_context_usage()` | 카테고리, 스킬 및 도구별 컨텍스트 윈도우 사용량의 분석 가져오기. 대화형 세션에서 `/context`가 표시하는 것과 동일한 데이터입니다. [`ContextUsageResponse`](#contextusageresponse)를 반환합니다. 분석을 계산하기 위해 Claude Code는 메시지 스트림에 나타나지 않는 여러 토큰 계산 API 요청을 수행합니다. [이러한 요청이 어떻게 처리되는지](#contextusageresponse) 참조 |
543| `reconnect_mcp_server(server_name)` | 실패했거나 연결이 끊긴 MCP 서버에 다시 연결 시도 |545| `reconnect_mcp_server(server_name)` | 실패했거나 연결이 끊긴 MCP 서버에 다시 연결 시도 |
544| `toggle_mcp_server(server_name, enabled)` | 세션 중간에 MCP 서버 활성화 또는 비활성화. 비활성화하면 도구 제거 |546| `toggle_mcp_server(server_name, enabled)` | 세션 중간에 MCP 서버 활성화 또는 비활성화. stdio, SSE 또는 HTTP 서버를 비활성화하면 해당 도구가 제거됩니다 |
545| `stop_task(task_id)` | 실행 중인 백그라운드 작업 중지. 상태 `"stopped"`인 [`TaskNotificationMessage`](#tasknotificationmessage)가 메시지 스트림에서 따릅니다 |547| `stop_task(task_id)` | 실행 중인 백그라운드 작업 중지. 상태 `"stopped"`인 [`TaskNotificationMessage`](#tasknotificationmessage)가 메시지 스트림에서 따릅니다 |
546| `get_server_info()` | 사용 가능한 명령 및 출력 스타일을 포함한 서버의 초기화 정보 가져오기 |548| `get_server_info()` | 사용 가능한 명령 및 출력 스타일을 포함한 서버의 초기화 정보 가져오기 |
547| `disconnect()` | Claude에서 연결 해제 |549| `disconnect()` | Claude에서 연결 해제 |
616 예제 - ClaudeSDKClient를 사용한 스트리밍 입력618 예제 - ClaudeSDKClient를 사용한 스트리밍 입력
617</h4>619</h4>
618 620
621`query()`는 사용자 메시지 딕셔너리의 비동기 반복 가능 객체도 허용하므로, 전송 시간에 프롬프트를 조립하거나 이미지와 같은 콘텐츠 블록을 포함할 수 있습니다. Claude Code는 반복 가능 객체가 완료될 때까지 기다리지 않고 첫 번째 생성된 메시지가 도착하는 즉시 응답을 시작하며, `receive_response()`는 해당 응답을 종료하는 `ResultMessage`에서 중지됩니다. Claude가 답변하기 전에 읽어야 할 모든 것을 이 생성기처럼 하나의 메시지에 넣고, 각 `query()` 호출을 자신의 `receive_response()` 루프와 쌍을 이루십시오.
622
619```python theme={null}623```python theme={null}
620import asyncio624import asyncio
621from claude_agent_sdk import ClaudeSDKClient625from claude_agent_sdk import ClaudeSDKClient
622 626
623 627
624async def message_stream():628async def message_stream():
625 """Generate messages dynamically."""629 """Assemble the prompt at send time and yield it as one user message."""
626 yield {630 readings = {"Temperature": "25°C", "Humidity": "60%"}
627 "type": "user",631 data = ", ".join(f"{name}: {value}" for name, value in readings.items())
628 "message": {"role": "user", "content": "Analyze the following data:"},
629 }
630 await asyncio.sleep(0.5)
631 yield {
632 "type": "user",
633 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
634 }
635 await asyncio.sleep(0.5)
636 yield {632 yield {
637 "type": "user",633 "type": "user",
638 "message": {"role": "user", "content": "What patterns do you see?"},634 "message": {
635 "role": "user",
636 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",
637 },
639 }638 }
640 639
641 640
1012| `type` | 예 | 프리셋 시스템 프롬프트를 사용하려면 `"preset"`이어야 합니다 |1011| `type` | 예 | 프리셋 시스템 프롬프트를 사용하려면 `"preset"`이어야 합니다 |
1013| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |1012| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |
1014| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |1013| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |
1015| `exclude_dynamic_sections` | 아니오 | 작업 디렉토리, git 상태 및 메모리 경로와 같은 세션별 컨텍스트를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |1014| `exclude_dynamic_sections` | 아니오 | 사용자별 컨텍스트 (예: 자동 메모리 위치)를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |
1016| `snapshot` | 아니오 | `False`로 설정하여 [세션이 첫 요청에서 기록한 프롬프트를 재사용](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. Python Agent SDK 0.2.153 이상 필요 |1015| `snapshot` | 아니오 | `False`로 설정하여 [세션이 첫 요청에서 기록한 프롬프트를 재사용](/docs/ko/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 대신 모든 요청에서 시스템 프롬프트를 다시 빌드합니다. Python Agent SDK 0.2.153 이상 필요 |
1017 1016
1018<h3 id="systempromptcustom">1017<h3 id="systempromptcustom">
1607| `scope` | `str` (선택사항) | 구성 범위 |1606| `scope` | `str` (선택사항) | 구성 범위 |
1608| `tools` | `list` (선택사항) | 이 서버가 제공하는 도구, 각각 `name`, `description` 및 `annotations` 필드 포함 |1607| `tools` | `list` (선택사항) | 이 서버가 제공하는 도구, 각각 `name`, `description` 및 `annotations` 필드 포함 |
1609 1608
1609<h3 id="contextusageresponse">
1610 `ContextUsageResponse`
1611</h3>
1612
1613[`ClaudeSDKClient.get_context_usage()`](#methods)의 응답입니다. 이것은 Claude Code가 대화형 세션에서 `/context` 명령을 위해 렌더링하는 것과 동일한 페이로드이므로, 토큰 수 외에도 Claude Code가 `/context` 사용량 그리드를 그리는 데 사용하는 `color` 및 `gridRows`와 같은 표시 필드를 포함합니다.
1614
1615Claude Code는 [토큰 계산](https://platform.claude.com/docs/en/build-with-claude/token-counting) API에 여러 요청을 보내 이 페이로드를 빌드합니다. 이 요청은 메시지 스트림에 나타나지 않으므로, 스트림을 읽는 비용 추적은 이를 보지 못합니다. Anthropic API에서 토큰 계산은 청구되지 않습니다.
1616
1617```python theme={null}
1618class ContextUsageResponse(TypedDict):
1619 categories: list[ContextUsageCategory]
1620 totalTokens: int
1621 maxTokens: int
1622 rawMaxTokens: int
1623 percentage: float
1624 model: str
1625 isAutoCompactEnabled: bool
1626 memoryFiles: list[dict[str, Any]]
1627 mcpTools: list[dict[str, Any]]
1628 agents: list[dict[str, Any]]
1629 gridRows: list[list[dict[str, Any]]]
1630 autoCompactThreshold: NotRequired[int]
1631 deferredBuiltinTools: NotRequired[list[dict[str, Any]]]
1632 systemTools: NotRequired[list[dict[str, Any]]]
1633 systemPromptSections: NotRequired[list[dict[str, Any]]]
1634 slashCommands: NotRequired[dict[str, Any]]
1635 skills: NotRequired[dict[str, Any]] # skill usage with frontmatter breakdown
1636 messageBreakdown: NotRequired[dict[str, Any]] # message tokens by type
1637 apiUsage: NotRequired[dict[str, Any] | None]
1638```
1639
1640각 `ContextUsageCategory` 항목은 `name`, `tokens`, `color` 및 선택적 `isDeferred` 플래그를 포함합니다. `totalTokens`는 세션의 현재 컨텍스트 사용량이고, `maxTokens`는 사용량이 측정되는 윈도우입니다. 해당 윈도우는 모델의 컨텍스트 윈도우이거나, 적용되는 자동 압축 윈도우이며, `rawMaxTokens`는 `maxTokens`와 동일한 값을 포함합니다. `apiUsage`는 세션의 실행 총계가 아닌 최신 API 응답의 사용량을 보유합니다. Claude Code는 선택적 `deferredBuiltinTools`, `systemTools` 및 `systemPromptSections` 키를 설정하지 않으므로, 타입이 이를 선언하더라도 이들이 없을 것으로 예상합니다.
1641
1610<h3 id="sdkpluginconfig">1642<h3 id="sdkpluginconfig">
1611 `SdkPluginConfig`1643 `SdkPluginConfig`
1612</h3>1644</h3>
2712 2744
2713모든 기본 Claude Code 도구의 입력/출력 스키마 문서입니다. Python SDK는 이들을 타입으로 내보내지 않지만, 메시지의 도구 입력 및 출력 구조를 나타냅니다.2745모든 기본 Claude Code 도구의 입력/출력 스키마 문서입니다. Python SDK는 이들을 타입으로 내보내지 않지만, 메시지의 도구 입력 및 출력 구조를 나타냅니다.
2714 2746
2747각 출력은 해당 도구에 대해 [`UserMessage.tool_use_result`](#usermessage)에서 읽는 값입니다. 키 이름은 Claude Code가 내보내는 그대로 나타납니다. `| None`으로 주석이 달린 키와 "present when" 또는 "optional" 주석이 있는 키는 적용되지 않을 때 생략됩니다.
2748
2715<h3 id="agent">2749<h3 id="agent">
2716 Agent2750 Agent
2717</h3>2751</h3>
2805```python theme={null}2839```python theme={null}
2806{2840{
2807 "status": "remote_launched",2841 "status": "remote_launched",
2808 "taskId": str, # 원격 작업의 ID2842 "taskId": str, # 전달된 작업의 ID
2809 "sessionUrl": str, # 원격 클라우드 세션으로의 링크2843 "sessionUrl": str, # 클라우드 세션으로의 링크
2810 "description": str, # 작업 설명2844 "description": str, # 작업 설명
2811 "prompt": str, # 에이전트가 실행하는 프롬프트2845 "prompt": str, # 에이전트가 실행하는 프롬프트
2812 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로2846 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로
2813}2847}
2814```2848```
2815 2849
2816서브에이전트의 결과를 반환합니다. 출력은 `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 원격 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`. `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지](/docs/ko/worktrees#isolate-subagents-with-worktrees)한 경우, `completed` 변형의 `worktreePath`는 이를 찾을 수 있는 위치이고, `worktreeBranch`는 Claude Code가 git으로 worktree를 생성했을 때의 브랜치입니다.2850서브에이전트의 결과를 반환합니다. 출력은 `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`. `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지](/docs/ko/worktrees#isolate-subagents-with-worktrees)한 경우, `completed` 변형의 `worktreePath`는 이를 찾을 수 있는 위치이고, `worktreeBranch`는 Claude Code가 git으로 worktree를 생성했을 때의 브랜치입니다.
2817 2851
2818`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작한 모델을 이름 지으며, 이는 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 또는 다른 오버라이드가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중인 모델을 이름 지으므로, 백그라운드 전환 전에 발생한 스왑이 반영됩니다. `modelsUsed` 필드는 두 변형 모두에서 순서대로 사용된 모델을 나열하며, 연속 반복은 축소됩니다. 실행 중에 모델이 교체되었을 때만 설정됩니다. `modelsUsed`와 백그라운드 시간 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.2852`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작한 모델을 이름 지으며, 이는 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 또는 다른 오버라이드가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중인 모델을 이름 지으므로, 백그라운드 전환 전에 발생한 스왑이 반영됩니다. `modelsUsed` 필드는 두 변형 모두에서 순서대로 사용된 모델을 나열하며, 연속 반복은 축소됩니다. 실행 중에 모델이 교체되었을 때만 설정됩니다. `modelsUsed`와 백그라운드 시간 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.
2819 2853
2820Claude Code는 전체 실행이 아닌 서브에이전트의 최종 API 요청에서 `usage`와 `totalTokens`를 채웁니다. `usage`의 `output_tokens_details` 아래 `thinking_tokens`이 있을 때, 이는 해당 요청의 출력 토큰 중 생각 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 하는 Python SDK v0.2.136 이상이 필요합니다.2854Claude Code는 전체 실행이 아닌 서브에이전트의 최종 API 요청에서 `usage`와 `totalTokens`를 채웁니다. 존재할 때, `usage`의 `output_tokens_details` 아래 `thinking_tokens`은 해당 요청의 출력 토큰 중 생각 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 하는 Python SDK v0.2.136 이상이 필요합니다.
2821 2855
2822<h3 id="askuserquestion">2856<h3 id="askuserquestion">
2823 AskUserQuestion2857 AskUserQuestion
2885 2919
2886**도구 이름:** `Bash`2920**도구 이름:** `Bash`
2887 2921
2888전경 상한선을 설정하는 것에 대해서는 [시간 초과 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하십시오. 백그라운드 시간 제한에 대해서는 [백그라운드 명령](/docs/ko/tools-reference#background-commands)을 참조하십시오.2922전경 상한선을 설정하는 것에 대해서는 [시간 초과 및 출력 제한](/docs/ko/tools-reference#timeout-and-output-limits)을 참조하십시오. 백그라운드 시간 제한에 대해서는 [백그라운드 명령의 시간 제한](/docs/ko/tools-reference#time-limit-for-background-commands)을 참조하십시오.
2889 2923
2890**입력:**2924**입력:**
2891 2925
2962 2996
2963```python theme={null}2997```python theme={null}
2964{2998{
2965 "message": str, # 확인 메시지2999 "filePath": str, # 편집된 파일
2966 "replacements": int, # 수행된 바꾸기 수3000 "oldString": str, # 바뀐 텍스트
2967 "file_path": str, # 편집된 파일 경로3001 "newString": str, # 이를 대체한 텍스트
3002 "originalFile": str | None, # 편집 전 파일 내용
3003 "structuredPatch": [ # 변경에 대한 Diff 청크
3004 {
3005 "oldStart": int,
3006 "oldLines": int,
3007 "newStart": int,
3008 "newLines": int,
3009 "lines": list[str],
3010 }
3011 ],
3012 "userModified": bool, # 사용자가 제안된 편집을 수락하기 전에 변경했는지 여부
3013 "replaceAll": bool, # 모든 항목이 바뀌었는지 여부
3014 "gitDiff": { # 파일에 대한 선택적 git diff 요약
3015 "filename": str,
3016 "status": "modified" | "added",
3017 "additions": int,
3018 "deletions": int,
3019 "changes": int,
3020 "patch": str,
3021 "repository": str | None, # 사용 가능할 때 GitHub owner/repo
3022 } | None,
2968}3023}
2969```3024```
2970 3025
2984}3039}
2985```3040```
2986 3041
2987**출력 (텍스트 파일):**3042Claude가 읽은 내용에 따라 출력은 다음 형태 중 하나를 취합니다. `type` 키를 확인하여 구분하십시오.
3043
3044**출력 (type: `"text"`):**
3045
3046```python theme={null}
3047{
3048 "type": "text",
3049 "file": {
3050 "filePath": str, # 읽은 파일
3051 "content": str, # 반환된 콘텐츠
3052 "numLines": int, # 반환된 콘텐츠의 줄 수
3053 "startLine": int, # 콘텐츠가 시작되는 줄 번호
3054 "totalLines": int, # 파일의 총 줄 수
3055 "truncatedByTokenCap": bool | None, # 전체 파일 읽기가 토큰 상한을 초과했을 때 표시되고 True이며 콘텐츠는 첫 페이지입니다
3056 },
3057}
3058```
3059
3060**출력 (type: `"image"`):**
3061
3062```python theme={null}
3063{
3064 "type": "image",
3065 "file": {
3066 "base64": str, # Base64로 인코딩된 이미지 데이터
3067 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # 이미지 MIME 타입
3068 "originalSize": int, # 원본 파일 크기(바이트)
3069 "dimensions": { # 좌표 매핑을 위한 선택적 크기 정보
3070 "originalWidth": int | None, # 선택적; 원본 너비(픽셀)
3071 "originalHeight": int | None, # 선택적; 원본 높이(픽셀)
3072 "displayWidth": int | None, # 선택적; 크기 조정 후 너비
3073 "displayHeight": int | None, # 선택적; 크기 조정 후 높이
3074 } | None,
3075 },
3076}
3077```
3078
3079**출력 (type: `"notebook"`):**
3080
3081```python theme={null}
3082{
3083 "type": "notebook",
3084 "file": {
3085 "filePath": str, # 읽은 노트북
3086 "cells": list, # 노트북 셀
3087 },
3088}
3089```
3090
3091**출력 (type: `"pdf"`):**
3092
3093```python theme={null}
3094{
3095 "type": "pdf",
3096 "file": {
3097 "filePath": str, # 읽은 PDF
3098 "base64": str, # Base64로 인코딩된 PDF 데이터
3099 "originalSize": int, # 파일 크기(바이트)
3100 },
3101}
3102```
3103
3104**출력 (type: `"parts"`):**
2988 3105
2989```python theme={null}3106```python theme={null}
2990{3107{
2991 "content": str, # 줄 번호가 있는 파일 내용3108 "type": "parts",
2992 "total_lines": int, # 파일의 총 줄 수3109 "file": {
2993 "lines_returned": int, # 실제로 반환된 줄3110 "filePath": str, # 읽은 PDF
3111 "originalSize": int, # 파일 크기(바이트)
3112 "count": int, # 이미지로 추출된 페이지 수
3113 "outputDir": str, # 추출된 페이지 이미지를 포함하는 디렉토리
3114 },
3115 "firstPage": int | None, # 선택적 추출된 첫 페이지의 문서 페이지 번호
2994}3116}
2995```3117```
2996 3118
2997**출력 (이미지):**3119**출력 (type: `"file_unchanged"`):**
2998 3120
2999```python theme={null}3121```python theme={null}
3000{3122{
3001 "image": str, # Base64로 인코딩된 이미지 데이터3123 "type": "file_unchanged", # 파일은 Claude가 이 세션에서 마지막으로 읽은 이후 변경되지 않았으므로 콘텐츠가 반복되지 않습니다
3002 "mime_type": str, # 이미지 MIME 타입3124 "file": {
3003 "file_size": int, # 파일 크기(바이트)3125 "filePath": str,
3126 },
3127 "source": "seeded" | None, # 이전 복사본이 시작 시 로드된 CLAUDE.md 또는 메모리 파일에서 나온 경우 표시됨
3004}3128}
3005```3129```
3006 3130
3015```python theme={null}3139```python theme={null}
3016{3140{
3017 "file_path": str, # 쓸 파일의 절대 경로3141 "file_path": str, # 쓸 파일의 절대 경로
3018 "content": str, # 파일에 쓸 내용3142 "content": str, # 파일에 쓸 콘텐츠
3019}3143}
3020```3144```
3021 3145
3023 3147
3024```python theme={null}3148```python theme={null}
3025{3149{
3026 "message": str, # 성공 메시지3150 "type": "create" | "update", # 쓰기가 새 파일을 생성했는지 또는 기존 파일을 덮어썼는지 여부
3027 "bytes_written": int, # 쓴 바이트 수3151 "filePath": str, # 쓴 파일
3028 "file_path": str, # 쓴 파일 경로3152 "content": str, # 쓴 콘텐츠
3153 "structuredPatch": [ # Diff 청크; 새 파일, 아무것도 변경되지 않음, 또는 Claude Code가 diff를 건너뛴 경우 비어 있음
3154 {
3155 "oldStart": int,
3156 "oldLines": int,
3157 "newStart": int,
3158 "newLines": int,
3159 "lines": list[str],
3160 }
3161 ],
3162 "originalFile": str | None, # 이전 콘텐츠; 새 파일이거나 이전 콘텐츠가 너무 클 때 None
3163 "gitDiff": { # 파일에 대한 선택적 git diff 요약
3164 "filename": str,
3165 "status": "modified" | "added",
3166 "additions": int,
3167 "deletions": int,
3168 "changes": int,
3169 "patch": str,
3170 "repository": str | None, # 사용 가능할 때 GitHub owner/repo
3171 } | None,
3172 "userModified": bool | None, # 선택적; 사용자가 수락하기 전에 제안된 콘텐츠를 편집했는지 여부
3029}3173}
3030```3174```
3031 3175
3048 3192
3049```python theme={null}3193```python theme={null}
3050{3194{
3051 "matches": list[str], # 일치하는 파일 경로 배열3195 "durationMs": int, # 검색을 실행하는 데 걸린 시간(밀리초)
3052 "count": int, # 찾은 일치 수3196 "numFiles": int, # 반환된 경로 수, 모든 잘림 후
3053 "search_path": str, # 사용된 검색 디렉토리3197 "filenames": list[str], # 일치하는 파일 경로
3198 "truncated": bool, # 결과가 100파일 제한에서 잘렸는지 여부
3199 "totalMatches": int | None, # 선택적 잘림 전 일치하는 파일의 총 수; countIsComplete가 False일 때 하한
3200 "countIsComplete": bool | None, # 선택적; totalMatches가 정확한지 여부
3054}3201}
3055```3202```
3056 3203
3204`totalMatches`와 `countIsComplete`는 Claude Code v2.1.191 이상이 필요합니다.
3205
3057<h3 id="grep">3206<h3 id="grep">
3058 Grep3207 Grep
3059</h3>3208</h3>
3074 "-B": int | None, # 각 일치 전에 표시할 줄3223 "-B": int | None, # 각 일치 전에 표시할 줄
3075 "-A": int | None, # 각 일치 후에 표시할 줄3224 "-A": int | None, # 각 일치 후에 표시할 줄
3076 "-C": int | None, # 전후에 표시할 줄3225 "-C": int | None, # 전후에 표시할 줄
3226 "context": int | None, # 전후에 표시할 줄; -C는 별칭
3227 "-o": bool | None, # 각 줄의 일치한 부분만 인쇄
3077 "head_limit": int | None, # 출력을 처음 N개 줄/항목으로 제한3228 "head_limit": int | None, # 출력을 처음 N개 줄/항목으로 제한
3229 "offset": int | None, # head_limit을 적용하기 전에 처음 N개 줄/항목 건너뛰기
3078 "multiline": bool | None, # 다중 줄 모드 활성화3230 "multiline": bool | None, # 다중 줄 모드 활성화
3079}3231}
3080```3232```
3081 3233
3082**출력 (content 모드):**3234**출력:**
3083 3235
3084```python theme={null}3236```python theme={null}
3085{3237{
3086 "matches": [3238 "mode": "content" | "files_with_matches" | "count" | None, # 사용된 출력 모드
3087 {3239 "numFiles": int, # 결과의 파일 수; 콘텐츠 모드에서는 항상 0
3088 "file": str,3240 "filenames": list[str], # files_with_matches 모드의 일치하는 파일; 다른 모드에서는 비어 있음
3089 "line_number": int | None,3241 "content": str | None, # 콘텐츠 모드의 일치하는 줄, 또는 count 모드의 파일별 수
3090 "line": str,3242 "numLines": int | None, # 콘텐츠의 줄 수, 콘텐츠 모드에 표시됨
3091 "before_context": list[str] | None,3243 "numMatches": int | None, # 총 일치 수, count 모드에 표시됨
3092 "after_context": list[str] | None,3244 "totalFiles": int | None, # 선택적 head_limit과 offset 전 총 수, files_with_matches 모드
3093 }3245 "totalLines": int | None, # 선택적 head_limit과 offset 전 총 수, 콘텐츠 모드
3094 ],3246 "appliedLimit": int | None, # head_limit이 결과를 잘랐을 때 표시됨
3095 "total_matches": int,3247 "appliedOffset": int | None, # offset이 적용되었을 때 표시됨
3096}3248}
3097```3249```
3098 3250
3099**출력 (files\_with\_matches 모드):**3251Grep은 각 출력 모드에서 이 dict 형태를 반환합니다. 어떤 선택적 키가 표시되는지는 `output_mode`에 따라 다릅니다.
3100 3252
3101```python theme={null}3253`totalFiles`는 Claude Code v2.1.208 이상이 필요합니다. `totalLines`는 Claude Code v2.1.210 이상이 필요합니다.
3102{
3103 "files": list[str], # 일치를 포함하는 파일
3104 "count": int, # 일치를 포함하는 파일 수
3105}
3106```
3107 3254
3108<h3 id="notebookedit">3255<h3 id="notebookedit">
3109 NotebookEdit3256 NotebookEdit
3127 3274
3128```python theme={null}3275```python theme={null}
3129{3276{
3130 "message": str, # 성공 메시지3277 "new_source": str, # 셀에 쓴 소스
3131 "edit_type": "replaced" | "inserted" | "deleted", # 수행된 편집 타입3278 "old_source": str | None, # 이전 셀 소스, replace와 delete에 표시됨
3132 "cell_id": str | None, # 영향을 받은 셀 ID3279 "cell_id": str | None, # 편집된 셀의 ID, 사용 가능할 때
3133 "total_cells": int, # 편집 후 노트북의 총 셀 수3280 "cell_type": "code" | "markdown", # 셀 타입
3281 "language": str, # 노트북의 프로그래밍 언어
3282 "edit_mode": str, # 사용된 편집 모드
3283 "error": str | None, # 작업이 실패했을 때 오류 메시지
3284 "notebook_path": str, # 노트북 파일
3285 "original_file": str, # 편집 전 노트북 콘텐츠
3286 "updated_file": str, # 편집 후 노트북 콘텐츠
3134}3287}
3135```3288```
3136 3289
3228 3381
3229```python theme={null}3382```python theme={null}
3230{3383{
3231 "message": str, # 성공 메시지3384 "oldTodos": [ # 업데이트 전 할 일 목록
3232 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3385 {
3386 "content": str,
3387 "status": "pending" | "in_progress" | "completed",
3388 "activeForm": str,
3389 }
3390 ],
3391 "newTodos": [ # 업데이트 후 할 일 목록
3392 {
3393 "content": str,
3394 "status": "pending" | "in_progress" | "completed",
3395 "activeForm": str,
3396 }
3397 ],
3233}3398}
3234```3399```
3235 3400
3401 3566
3402```python theme={null}3567```python theme={null}
3403{3568{
3404 "message": str, # 확인 메시지3569 "plan": str | None, # 사용자에게 제시된 계획
3405 "approved": bool | None, # 사용자가 계획을 승인했는지 여부3570 "isAgent": bool, # 서브에이전트가 도구를 호출했을 때 True
3571 "filePath": str | None, # 계획이 파일에 저장되었을 때 표시됨
3572 "hasTaskTool": bool | None, # 선택적; 현재 컨텍스트에서 Agent 도구를 사용할 수 있는지 여부
3573 "planWasEdited": bool | None, # 사용자가 승인하기 전에 계획을 편집했을 때 표시되고 True
3574 "awaitingLeaderApproval": bool | None, # 팀원이 팀 리더에게 승인을 위해 계획을 보냈을 때 표시되고 True
3575 "requestId": str | None, # 선택적 해당 승인 요청의 ID
3406}3576}
3407```3577```
3408 3578
3420}3590}
3421```3591```
3422 3592
3593결과는 dict가 아닌 list이므로, `tool_use_result`는 이 도구에 대해 `list`를 보유합니다.
3594
3423**출력:**3595**출력:**
3424 3596
3425```python theme={null}3597```python theme={null}
3426{3598[ # 리소스당 하나의 항목
3427 "resources": [
3428 {3599 {
3429 "uri": str,3600 "uri": str, # 리소스 URI
3430 "name": str,3601 "name": str, # 리소스 이름
3431 "description": str | None,3602 "mimeType": str | None, # 선택적 MIME 타입
3432 "mimeType": str | None,3603 "description": str | None, # 선택적 설명
3433 "server": str,3604 "server": str, # 이 리소스를 제공하는 서버
3434 }3605 }
3435 ],3606]
3436 "total": int,
3437}
3438```3607```
3439 3608
3440<h3 id="readmcpresource">3609<h3 id="readmcpresource">
3457```python theme={null}3626```python theme={null}
3458{3627{
3459 "contents": [3628 "contents": [
3460 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3629 {
3630 "uri": str, # 리소스 URI
3631 "mimeType": str | None, # 선택적 MIME 타입
3632 "text": str | None, # 텍스트 콘텐츠, 또는 바이너리 콘텐츠에 대한 노트
3633 "blobSavedTo": str | None, # Claude Code가 바이너리 콘텐츠를 디스크에 저장했을 때 표시됨; 저장된 파일의 경로
3634 }
3461 ],3635 ],
3462 "server": str,3636 "error": str | None, # 서버가 리소스를 읽을 수 없을 때 표시됨
3463}3637}
3464```3638```
3465 3639
