2564 2564
2565## 도구 입력/출력 타입2565## 도구 입력/출력 타입
2566 2566
2567기본 제공 Claude Code 도구의 입력/출력 스키마 문서입니다. Python SDK는 이들을 타입으로 내보내지 않지만, 메시지의 도구 입력 및 출력 구조를 나타냅니다.2567기본 제공 Claude Code 도구의 입력/출력 스키마에 대한 문서입니다. Python SDK는 이를 타입으로 export하지 않지만, 이 스키마는 메시지에 포함된 도구 입력과 출력의 구조를 나타냅니다.
2568 2568
2569각 출력은 해당 도구에 대해 [`UserMessage.tool_use_result`](#usermessage)에서 읽는 값입니다. 키 이름은 Claude Code가 내보내는 그대로 나타납니다. `| None`으로 주석이 달린 키와 "present when" 또는 "optional" 주석이 있는 키는 적용되지 않을 때 생략됩니다.2569아래에 표시된 각 출력은 해당 도구에 대해 [`UserMessage.tool_use_result`](#usermessage)에서 읽는 값입니다. 키 이름은 Claude Code가 내보내는 그대로 표시됩니다. `| None`으로 표시되고 "present when" 또는 "optional" 주석이 달린 키는 해당되지 않을 때 생략됩니다.
2570 2570
2571### Agent2571### Agent
2572 2572
2573**도구 이름:** `Agent`. 이전 이름 `Task`는 이 도구를 세션에서 사용할 수 있을 때 여전히 별칭으로 허용됩니다.2573**도구 이름:** `Agent`. 이 도구를 세션에서 사용할 수 있는 경우 이전 이름인 `Task`도 별칭으로 계속 허용됩니다.
2574 2574
2575init [`SystemMessage`](#systemmessage)의 `tools` 목록은 하위 호환성을 위해 이 도구를 `Task`로 보고합니다.2575init [`SystemMessage`](#systemmessage)의 `tools` 목록은 하위 호환성을 위해 이 도구를 `Task`로 보고합니다.
2576 2576
2578 2578
2579```python theme={null}2579```python theme={null}
2580{2580{
2581 "description": str, # 작업의 짧은 설명 (3-5단어)2581 "description": str, # 작업에 대한 짧은(3~5단어) 설명
2582 "prompt": str, # 에이전트가 수행할 작업2582 "prompt": str, # 에이전트가 수행할 작업
2583 "subagent_type": str | None, # 사용할 특화된 에이전트의 유형2583 "subagent_type": str | None, # 사용할 전문 에이전트의 유형
2584 "model": "sonnet" | "opus" | "haiku" | "fable" | None, # 이 에이전트의 모델 재정의2584 "model": "sonnet" | "opus" | "haiku" | "fable" | None, # 이 에이전트에 대한 모델 재정의
2585 "effort": "low" | "medium" | "high" | "xhigh" | "max" | None, # 이 에이전트의 추론 노력 수준2585 "effort": "low" | "medium" | "high" | "xhigh" | "max" | None, # 이 에이전트의 추론 노력 수준
2586 "run_in_background": bool | None, # 생략 시 기본값: 메인 에이전트의 호출은 새 에이전트를 백그라운드에서 실행하고, 서브에이전트의 호출은 새 에이전트를 기다립니다2586 "run_in_background": bool | None, # 생략 시 기본값: 메인 에이전트의 호출은 새 에이전트를 백그라운드에서 실행하고, 서브에이전트의 호출은 새 에이전트를 기다림
2587 "name": str | None, # 생성된 에이전트의 이름2587 "name": str | None, # 생성되는 에이전트의 이름
2588 "team_name": str | None, # 더 이상 사용되지 않음; 무시됨2588 "team_name": str | None, # deprecated; 무시됨
2589 "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None, # 더 이상 사용되지 않음; 무시됨. 서브에이전트 상속 규칙이 서브에이전트의 권한 모드를 결정합니다2589 "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None, # deprecated; 무시됨. 서브에이전트의 권한 모드는 서브에이전트 상속 규칙에 따라 결정됨
2590 "isolation": "worktree" | "remote" | None, # 에이전트 변경 사항의 격리 모드2590 "isolation": "worktree" | "remote" | None, # 에이전트 변경 사항에 대한 격리 모드
2591}2591}
2592```2592```
2593 2593
2594복잡한 다단계 작업을 자율적으로 처리하기 위해 새로운 에이전트를 시작합니다.2594복잡한 다단계 작업을 자율적으로 처리하기 위해 새 에이전트를 실행합니다.
2595 2595
2596Claude가 `Agent` 호출에서 `run_in_background`를 생략하면, 기본적으로 메인 에이전트는 새 에이전트를 기다리지 않고 서브에이전트는 기다립니다:2596Claude가 `Agent` 호출에서 `run_in_background`를 생략하면, 기본적으로 메인 에이전트는 새 에이전트를 기다리지 않고 서브에이전트는 기다립니다.
2597 2597
2598* **메인 에이전트에서**: 새 에이전트는 백그라운드에서 실행되며, 결과에는 `status: "async_launched"`가 포함됩니다. 대신 메인 에이전트가 새 에이전트를 기다리도록 하려면 [Claude가 서브에이전트를 기다릴지 선택하기](https://code.claude.com/docs/ko/agent-sdk/subagents.md#choose-whether-claude-waits-for-subagents)를 참조하십시오.2598* **메인 에이전트에서 호출한 경우**: 새 에이전트가 백그라운드에서 실행되며, 결과에는 `status: "async_launched"`가 포함됩니다. 메인 에이전트가 대신 새 에이전트를 기다리게 하려면 [Claude가 서브에이전트를 기다릴지 선택하기](https://code.claude.com/docs/ko/agent-sdk/subagents.md#choose-whether-claude-waits-for-subagents)를 참조하세요.
2599* **서브에이전트 중 하나에서**: 호출한 서브에이전트가 [새 에이전트를 기다립니다](https://code.claude.com/docs/ko/sub-agents.md#let-subagents-spawn-their-own-subagents). 새 에이전트의 정의에서 [`background`](#agentdefinition)를 `True`로 설정하거나, `CLAUDE_CODE_FORK_SUBAGENT`를 `0`으로 설정하여 [포크 모드를 끄면](https://code.claude.com/docs/ko/sub-agents.md#turn-fork-mode-on-or-off) 새 에이전트가 대신 백그라운드에서 실행됩니다.2599* **서브에이전트 중 하나에서 호출한 경우**: 호출한 서브에이전트가 [새 에이전트를 기다립니다](https://code.claude.com/docs/ko/sub-agents.md#let-subagents-spawn-their-own-subagents). 새 에이전트의 정의에서 [`background`](#agentdefinition)를 `True`로 설정하거나, `CLAUDE_CODE_FORK_SUBAGENT`를 `0`으로 설정하여 [fork 모드를 끄면](https://code.claude.com/docs/ko/sub-agents.md#turn-fork-mode-on-or-off) 새 에이전트가 대신 백그라운드에서 실행됩니다.
2600 2600
2601Python SDK v0.2.169 이전에는 서브에이전트가 시작한 에이전트도 기본적으로 백그라운드에서 실행되었습니다. 해당 릴리스는 Claude Code v2.1.302 이상을 번들로 포함하는 첫 번째 릴리스입니다.2601Python SDK v0.2.169 이전에는 서브에이전트가 시작한 에이전트도 기본적으로 백그라운드에서 실행되었습니다. 해당 릴리스는 Claude Code v2.1.302 이상을 번들로 포함하는 첫 번째 릴리스입니다.
2602 2602
2603**출력 (상태: `"completed"`):**2603**출력 (status: `"completed"`):**
2604 2604
2605```python theme={null}2605```python theme={null}
2606{2606{
2614 "citations": list | None,2614 "citations": list | None,
2615 }2615 }
2616 ],2616 ],
2617 "resolvedModel": str | None, # 서브에이전트가 시작한 모델2617 "resolvedModel": str | None, # 서브에이전트가 시작할 때 사용한 모델
2618 "modelsUsed": list[str] | None, # 순서대로 사용된 모델, 연속 반복은 축소됨2618 "modelsUsed": list[str] | None, # 사용된 모델 목록(순서대로, 연속 중복은 하나로 합침)
2619 "totalToolUseCount": int, # 에이전트가 수행한 도구 호출 수2619 "totalToolUseCount": int, # 에이전트가 수행한 도구 호출 수
2620 "totalDurationMs": int, # 실행 시간(밀리초)2620 "totalDurationMs": int, # 실행 시간(밀리초)
2621 "totalTokens": int, # 전체 실행이 아닌 최종 API 요청의 토큰 수2621 "totalTokens": int, # 전체 실행이 아닌 마지막 API 요청의 토큰 수
2622 "usage": { # 토큰 사용 통계2622 "usage": { # 토큰 사용량 통계
2623 "input_tokens": int,2623 "input_tokens": int,
2624 "output_tokens": int,2624 "output_tokens": int,
2625 "cache_creation_input_tokens": int | None,2625 "cache_creation_input_tokens": int | None,
2633 "output_tokens_details": {"thinking_tokens": int | None} | None,2633 "output_tokens_details": {"thinking_tokens": int | None} | None,
2634 "fallback_credit": Any | None,2634 "fallback_credit": Any | None,
2635 },2635 },
2636 "toolStats": { # 실행의 집계 도구 활동2636 "toolStats": { # 실행 전체의 도구 활동 집계
2637 "readCount": int,2637 "readCount": int,
2638 "searchCount": int,2638 "searchCount": int,
2639 "bashCount": int,2639 "bashCount": int,
2644 "frameCount": int | None,2644 "frameCount": int | None,
2645 } | None,2645 } | None,
2646 "prompt": str, # 에이전트가 실행한 프롬프트2646 "prompt": str, # 에이전트가 실행한 프롬프트
2647 "worktreePath": str | None, # Claude Code가 서브에이전트의 worktree를 유지했을 때 표시됨2647 "worktreePath": str | None, # Claude Code가 서브에이전트의 worktree를 유지한 경우 존재
2648 "worktreeBranch": str | None, # Claude Code가 해당 worktree를 git으로 생성했을 때 표시됨2648 "worktreeBranch": str | None, # Claude Code가 git으로 해당 worktree를 생성한 경우 존재
2649}2649}
2650```2650```
2651 2651
2652**출력 (상태: `"async_launched"`):**2652**출력 (status: `"async_launched"`):**
2653 2653
2654```python theme={null}2654```python theme={null}
2655{2655{
2656 "status": "async_launched",2656 "status": "async_launched",
2657 "isAsync": bool | None, # 백그라운드 시작 시 True2657 "isAsync": bool | None, # 백그라운드 실행 시 True
2658 "agentId": str, # 시작된 에이전트의 ID2658 "agentId": str, # 실행된 에이전트의 ID
2659 "description": str, # 작업 설명2659 "description": str, # 작업 설명
2660 "resolvedModel": str | None, # 백그라운드 전환 시 사용 중인 모델2660 "resolvedModel": str | None, # 백그라운드로 전환되는 시점에 사용 중이던 모델
2661 "modelsUsed": list[str] | None, # 백그라운드 전환 전에 사용된 모델, 순서대로, 연속 반복은 축소됨2661 "modelsUsed": list[str] | None, # 백그라운드 전환 전에 사용된 모델 목록(순서대로, 연속 중복은 하나로 합침)
2662 "prompt": str, # 에이전트가 실행하는 프롬프트2662 "prompt": str, # 에이전트가 실행하는 프롬프트
2663 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로2663 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로
2664 "canReadOutputFile": bool | None, # 출력 파일을 직접 읽을 수 있는지 여부2664 "canReadOutputFile": bool | None, # 출력 파일을 직접 읽을 수 있는지 여부
2665}2665}
2666```2666```
2667 2667
2668**출력 (상태: `"remote_launched"`):**2668**출력 (status: `"remote_launched"`):**
2669 2669
2670```python theme={null}2670```python theme={null}
2671{2671{
2672 "status": "remote_launched",2672 "status": "remote_launched",
2673 "taskId": str, # 전달된 작업의 ID2673 "taskId": str, # 디스패치된 작업의 ID
2674 "sessionUrl": str, # 클라우드 세션으로의 링크2674 "sessionUrl": str, # 클라우드 세션 링크
2675 "description": str, # 작업 설명2675 "description": str, # 작업 설명
2676 "prompt": str, # 에이전트가 실행하는 프롬프트2676 "prompt": str, # 에이전트가 실행하는 프롬프트
2677 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로2677 "outputFile": str, # 에이전트의 출력이 기록되는 파일 경로
2678}2678}
2679```2679```
2680 2680
2681서브에이전트의 결과를 반환합니다. 출력은 `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`. `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지](https://code.claude.com/docs/ko/worktrees.md#isolate-subagents-with-worktrees)한 경우, `completed` 변형의 `worktreePath`는 이를 찾을 수 있는 위치이고, `worktreeBranch`는 Claude Code가 git으로 worktree를 생성했을 때의 브랜치입니다.2681서브에이전트의 결과를 반환합니다. 출력은 `status` 필드로 구분됩니다. 완료된 작업은 `"completed"`, 백그라운드 작업은 `"async_launched"`, Claude Code가 클라우드 세션으로 디스패치한 작업은 `"remote_launched"`이며, 이 경우 `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 해당 세션을 식별합니다. Claude Code가 [서브에이전트의 격리된 worktree를 유지한 경우](https://code.claude.com/docs/ko/worktrees.md#isolate-subagents-with-worktrees), `completed` 변형의 `worktreePath`는 해당 worktree의 위치이며, Claude Code가 git으로 worktree를 생성한 경우 `worktreeBranch`는 해당 브랜치입니다.
2682 2682
2683`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작한 모델을 이름 지으며, 이는 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 또는 다른 재정의가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 이동했을 때 사용 중인 모델을 이름 지으므로, 백그라운드 전환 전에 발생한 스왑이 반영됩니다. `modelsUsed` 필드는 두 변형 모두에서 순서대로 사용된 모델을 나열하며, 연속 반복은 축소됩니다. 실행 중에 모델이 교체되었을 때만 설정됩니다. `modelsUsed`와 백그라운드 시간 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.2683`completed` 변형에서 `resolvedModel`은 서브에이전트가 시작할 때 사용한 모델을 나타내며, [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 또는 다른 재정의가 적용되는 경우 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다. `async_launched` 변형에서 `resolvedModel`은 에이전트가 백그라운드로 전환될 때 사용 중이던 모델을 나타내므로, 백그라운드 전환 전에 발생한 모델 교체가 여기에 반영됩니다. 두 변형 모두의 `modelsUsed` 필드는 사용된 모델을 순서대로 나열하며 연속 중복은 하나로 합칩니다. 이 필드는 실행 도중 모델이 교체된 경우에만 설정됩니다. `modelsUsed`와 백그라운드 전환 시점의 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.
2684 2684
2685Claude Code는 전체 실행이 아닌 서브에이전트의 최종 API 요청에서 `usage`와 `totalTokens`를 채웁니다. 존재할 때, `usage`의 `output_tokens_details` 아래 `thinking_tokens`은 해당 요청의 출력 토큰 중 사고 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 하는 Python SDK v0.2.136 이상이 필요합니다. `fallback_credit` 키는 Claude Code v2.1.285를 번들로 하는 Python SDK v0.2.162 이상이 필요합니다.2685Claude Code는 `usage`와 `totalTokens`를 전체 실행이 아닌 서브에이전트의 마지막 API 요청을 기준으로 채웁니다. `usage`의 `output_tokens_details` 아래에 `thinking_tokens`가 있는 경우, 이 값은 해당 요청의 출력 토큰 중 사고 토큰의 수입니다. `output_tokens_details` 키는 Claude Code v2.1.228을 번들로 포함하는 Python SDK v0.2.136 이상이 필요합니다. `fallback_credit` 키는 Claude Code v2.1.285를 번들로 포함하는 Python SDK v0.2.162 이상이 필요합니다.
2686 2686
2687### AskUserQuestion2687### AskUserQuestion
2688 2688
2689**도구 이름:** `AskUserQuestion`2689**도구 이름:** `AskUserQuestion`
2690 2690
2691실행 중에 사용자에게 명확히 하는 질문을 합니다. 사용 세부 정보는 [승인 및 사용자 입력 처리](https://code.claude.com/docs/ko/agent-sdk/user-input.md#handle-clarifying-questions)를 참조하십시오.2691실행 중에 사용자에게 명확히 하기 위한 질문을 합니다. 사용법에 대한 자세한 내용은 [승인 및 사용자 입력 처리](https://code.claude.com/docs/ko/agent-sdk/user-input.md#handle-clarifying-questions)를 참조하세요.
2692 2692
2693**입력:**2693**입력:**
2694 2694
2695```python theme={null}2695```python theme={null}
2696{2696{
2697 "questions": [ # 사용자에게 물어볼 질문 (1-4개 질문)2697 "questions": [ # 사용자에게 할 질문(1~4개)
2698 {2698 {
2699 "question": str, # 사용자에게 물어볼 완전한 질문2699 "question": str, # 사용자에게 할 전체 질문
2700 "header": str, # 칩/태그로 표시되는 매우 짧은 레이블 (최대 12자)2700 "header": str, # 칩/태그로 표시되는 매우 짧은 레이블(최대 12자)
2701 "options": [ # 사용 가능한 선택 (2-4개 옵션)2701 "options": [ # 사용 가능한 선택지(2~4개)
2702 {2702 {
2703 "label": str, # 이 옵션의 표시 텍스트 (1-5단어)2703 "label": str, # 이 옵션의 표시 텍스트(1~5단어)
2704 "description": str, # 이 옵션이 의미하는 바에 대한 설명2704 "description": str, # 이 옵션의 의미에 대한 설명
2705 "preview": str | None, # 옵션이 포커스될 때 렌더링되는 미리보기 콘텐츠2705 "preview": str | None, # 옵션에 포커스가 있을 때 렌더링되는 미리보기 콘텐츠
2706 }2706 }
2707 ],2707 ],
2708 "multiSelect": bool, # 여러 선택을 허용하려면 true로 설정2708 "multiSelect": bool, # 다중 선택을 허용하려면 true로 설정
2709 }2709 }
2710 ],2710 ],
2711 "answers": dict[str, str] | None,2711 "answers": dict[str, str] | None,
2712 # 권한 시스템에 의해 채워진 사용자 답변. 다중 선택2712 # 권한 시스템이 채우는 사용자 답변. 다중 선택
2713 # 답변은 선택된 레이블의 쉼표로 연결된 문자열입니다. 입력 시2713 # 답변은 선택된 레이블을 쉼표로 연결한 문자열이며,
2714 # 레이블 목록이 허용되고 해당 형식으로 강제됩니다2714 # 입력 시 레이블 목록도 허용되고 해당 형식으로 변환됨
2715 "annotations": dict[str, dict] | None,2715 "annotations": dict[str, dict] | None,
2716 # 질문 텍스트로 키가 지정된 사용자의 질문별 주석입니다.2716 # 질문 텍스트를 키로 하는 사용자의 질문별 주석.
2717 # 각 값은 "preview" (선택된 옵션의 미리보기2717 # 각 값에는 "preview"(선택된 옵션의 미리보기
2718 # 콘텐츠)와 "notes" (선택에 대한 자유 텍스트 노트)를 포함할 수 있습니다2718 # 콘텐츠)와 "notes"(선택에 대한 자유 텍스트 메모)가 포함될 수 있음
2719 "metadata": dict | None, # {"source": "remember"}와 같은 분석 메타데이터; 사용자에게 표시되지 않음2719 "metadata": dict | None, # {"source": "remember"}와 같은 분석용 메타데이터; 사용자에게 표시되지 않음
2720}2720}
2721```2721```
2722 2722
2724 2724
2725```python theme={null}2725```python theme={null}
2726{2726{
2727 "questions": [ # 물어본 질문2727 "questions": [ # 질문했던 내용
2728 {2728 {
2729 "question": str,2729 "question": str,
2730 "header": str,2730 "header": str,
2735 "answers": dict[str, str], # 질문 텍스트를 답변 문자열에 매핑2735 "answers": dict[str, str], # 질문 텍스트를 답변 문자열에 매핑
2736 # 다중 선택 답변은 쉼표로 구분됨2736 # 다중 선택 답변은 쉼표로 구분됨
2737 "response": str | None,2737 "response": str | None,
2738 # 질문에 답하는 대신 입력한 자유 형식 답변; 설정되면,2738 # 질문에 답하는 대신 입력한 자유 형식 응답; 설정된 경우
2739 # Claude는 답변 목록 대신 "The user responded: ..."를 받습니다2739 # Claude는 답변 목록 대신 "The user responded: ..."를 받음
2740 "annotations": dict[str, dict] | None, # 사용자의 선택에서 질문별 "preview"와 "notes"2740 "annotations": dict[str, dict] | None, # 사용자 선택에 대한 질문별 "preview" 및 "notes"
2741 "afkTimeoutMs": int | None, # 사용자 비활성 후 이 많은 밀리초 후 대화가 자동 해결되었을 때 설정됨; 사용자가 답변했을 때는 없음2741 "afkTimeoutMs": int | None, # 이 밀리초 동안 사용자가 활동하지 않아 대화 상자가 자동으로 종료된 경우 설정됨; 사용자가 답변한 경우 없음
2742}2742}
2743```2743```
2744 2744
2746 2746
2747**도구 이름:** `Bash`2747**도구 이름:** `Bash`
2748 2748
2749전경 상한선을 설정하는 것에 대해서는 [타임아웃 및 출력 제한](https://code.claude.com/docs/ko/tools-reference.md#timeout-and-output-limits)을 참조하십시오. 백그라운드 시간 제한에 대해서는 [백그라운드 명령의 시간 제한](https://code.claude.com/docs/ko/tools-reference.md#time-limit-for-background-commands)을 참조하십시오.2749포그라운드 상한을 결정하는 요소는 [타임아웃 및 출력 제한](https://code.claude.com/docs/ko/tools-reference.md#timeout-and-output-limits)을 참조하세요. 백그라운드 시간 제한은 [백그라운드 명령의 시간 제한](https://code.claude.com/docs/ko/tools-reference.md#time-limit-for-background-commands)을 참조하세요.
2750 2750
2751**입력:**2751**입력:**
2752 2752
2753```python theme={null}2753```python theme={null}
2754{2754{
2755 "command": str, # 실행할 명령2755 "command": str, # 실행할 명령
2756 "timeout": int | None, # 밀리초. 전경: 기본값 600000으로 제한되며, 더 높은 값은 고정됩니다. run_in_background (Claude Code v2.1.285 이상): 백그라운드 시간 제한, 생략 시 1800000, 상향 조정되지 않으면 7200000으로 제한됨2756 "timeout": int | None, # 밀리초. 포그라운드: 기본적으로 600000으로 제한되며, 더 큰 값은 잘림. run_in_background 사용 시(Claude Code v2.1.285 이상): 백그라운드 시간 제한으로, 생략 시 1800000이며 상향하지 않는 한 7200000으로 제한됨
2757 "description": str | None, # 명확하고 간결한 설명 (5-10단어)2757 "description": str | None, # 명확하고 간결한 설명(5~10단어)
2758 "run_in_background": bool | None, # 백그라운드에서 실행하려면 true로 설정2758 "run_in_background": bool | None, # 백그라운드에서 실행하려면 true로 설정
2759}2759}
2760```2760```
2763 2763
2764```python theme={null}2764```python theme={null}
2765{2765{
2766 "stdout": str, # 명령의 출력; stdout과 stderr는 이 하나의 인터리브된 스트림으로 병합됨2766 "stdout": str, # 명령의 출력; stdout과 stderr가 하나의 인터리브된 스트림으로 병합되어 전달됨
2767 "stderr": str, # 도구 자체가 추가하는 알림, 명령의 stderr가 아님2767 "stderr": str, # 명령의 stderr가 아닌, 도구 자체가 추가하는 알림
2768 "interrupted": bool, # 명령이 중단되었는지 여부2768 "interrupted": bool, # 명령이 중단되었는지 여부
2769 "isImage": bool | None, # stdout에 이미지 데이터가 포함되어 있는지 여부2769 "isImage": bool | None, # stdout에 이미지 데이터가 포함되어 있는지 여부
2770 "backgroundTaskId": str | None, # 명령이 백그라운드에서 실행 중일 때 백그라운드 작업의 ID2770 "backgroundTaskId": str | None, # 명령이 백그라운드에서 실행 중인 경우 백그라운드 작업의 ID
2771}2771}
2772```2772```
2773 2773
2775 2775
2776**도구 이름:** `Monitor`2776**도구 이름:** `Monitor`
2777 2777
2778백그라운드 소스를 실행하고 각 이벤트를 Claude에 전달하여 폴링 없이 반응할 수 있도록 합니다. `command`는 스크립트를 실행하고 stdout 줄당 하나의 이벤트를 내보내며, `ws`는 WebSocket을 열고 텍스트 프레임당 하나의 이벤트를 내보냅니다. `command` 또는 `ws` 중 정확히 하나를 제공하십시오.2778백그라운드 소스를 실행하고 각 이벤트를 Claude에 전달하여 폴링 없이 반응할 수 있게 합니다. `command`는 스크립트를 실행하고 stdout 한 줄마다 이벤트 하나를 내보내며, `ws`는 WebSocket을 열고 텍스트 프레임 하나마다 이벤트 하나를 내보냅니다. `command`와 `ws` 중 정확히 하나만 제공하세요.
2779 2779
2780Monitor가 명령을 실행할 때, Bash와 동일한 권한 규칙을 따릅니다. WebSocket 감시는 별도로 승인을 요청합니다. `ws` 소스는 Claude Code v2.1.195 이상이 필요합니다. 동작 및 제공자 가용성은 [Monitor 도구 참조](https://code.claude.com/docs/ko/tools-reference.md#monitor-tool)를 참조하십시오.2780Monitor가 명령을 실행할 때는 Bash와 동일한 권한 규칙을 따르며, WebSocket 감시는 별도로 승인을 요청합니다. `ws` 소스는 Claude Code v2.1.195 이상이 필요합니다. 동작과 제공업체별 사용 가능 여부는 [Monitor 도구 레퍼런스](https://code.claude.com/docs/ko/tools-reference.md#monitor-tool)를 참조하세요.
2781 2781
2782**입력:**2782**입력:**
2783 2783
2784```python theme={null}2784```python theme={null}
2785{2785{
2786 "command": str | None, # 셸 스크립트; 각 stdout 줄은 이벤트이고, 종료는 감시를 끝냅니다2786 "command": str | None, # 셸 스크립트; stdout 각 줄이 이벤트이며, 종료되면 감시가 끝남
2787 "ws": dict | None, # WebSocket 소스: {"url": str, "protocols": list[str] | None}; 각 텍스트 프레임은 이벤트입니다2787 "ws": dict | None, # WebSocket 소스: {"url": str, "protocols": list[str] | None}; 각 텍스트 프레임이 이벤트
2788 "description": str, # 알림에 표시되는 짧은 설명2788 "description": str, # 알림에 표시되는 짧은 설명
2789 "timeout_ms": int | None, # 밀리초 단위의 기한 (기본값 300000, 최대 3600000; 유효한 기한은 최대 1800000)2789 "timeout_ms": int | None, # 기한(밀리초)(기본값 300000, 최대 3600000; 실제 적용 기한은 최대 1800000)
2790}2790}
2791```2791```
2792 2792
2795```python theme={null}2795```python theme={null}
2796{2796{
2797 "taskId": str, # 백그라운드 모니터 작업의 ID2797 "taskId": str, # 백그라운드 모니터 작업의 ID
2798 "timeoutMs": int, # 밀리초 단위의 감시 유효 기한2798 "timeoutMs": int, # 감시의 실제 적용 기한(밀리초)
2799 "persistent": bool | None, # False: 모든 감시에는 기한이 있습니다2799 "persistent": bool | None, # False: 모든 감시에는 기한이 있음
2800}2800}
2801```2801```
2802 2802
2809```python theme={null}2809```python theme={null}
2810{2810{
2811 "file_path": str, # 수정할 파일의 절대 경로2811 "file_path": str, # 수정할 파일의 절대 경로
2812 "old_string": str, # 바꿀 텍스트2812 "old_string": str, # 교체될 기존 텍스트
2813 "new_string": str, # 바꿀 텍스트2813 "new_string": str, # 기존 텍스트를 대신할 새 텍스트
2814 "replace_all": bool | None, # 모든 항목 바꾸기 (기본값 False)2814 "replace_all": bool | None, # 모든 일치 항목 교체(기본값 False)
2815}2815}
2816```2816```
2817 2817
2820```python theme={null}2820```python theme={null}
2821{2821{
2822 "filePath": str, # 편집된 파일2822 "filePath": str, # 편집된 파일
2823 "oldString": str, # 바뀐 텍스트2823 "oldString": str, # 교체된 기존 텍스트
2824 "newString": str, # 이를 대체한 텍스트2824 "newString": str, # 기존 텍스트를 대신한 새 텍스트
2825 "originalFile": str | None, # 편집 전 파일 내용2825 "originalFile": str | None, # 편집 전 파일 내용
2826 "structuredPatch": [ # 변경에 대한 diff 청크2826 "structuredPatch": [ # 변경에 대한 diff 헝크
2827 {2827 {
2828 "oldStart": int,2828 "oldStart": int,
2829 "oldLines": int,2829 "oldLines": int,
2832 "lines": list[str],2832 "lines": list[str],
2833 }2833 }
2834 ],2834 ],
2835 "userModified": bool, # 사용자가 제안된 편집을 수락하기 전에 변경했는지 여부2835 "userModified": bool, # 사용자가 수락하기 전에 제안된 편집을 변경했는지 여부
2836 "replaceAll": bool, # 모든 항목이 바뀌었는지 여부2836 "replaceAll": bool, # 모든 일치 항목이 교체되었는지 여부
2837 "gitDiff": { # 파일에 대한 선택적 git diff 요약2837 "gitDiff": { # 파일에 대한 선택적 git diff 요약
2838 "filename": str,2838 "filename": str,
2839 "status": "modified" | "added",2839 "status": "modified" | "added",
2841 "deletions": int,2841 "deletions": int,
2842 "changes": int,2842 "changes": int,
2843 "patch": str,2843 "patch": str,
2844 "repository": str | None, # 사용 가능할 때 GitHub owner/repo2844 "repository": str | None, # 사용 가능한 경우 GitHub owner/repo
2845 } | None,2845 } | None,
2846}2846}
2847```2847```
2860}2860}
2861```2861```
2862 2862
2863Claude가 읽은 내용에 따라 출력은 다음 형태 중 하나를 취합니다. `type` 키를 확인하여 구분하십시오.2863출력은 Claude가 읽은 대상에 따라 다음 형태 중 하나를 가집니다. `type` 키를 확인하여 구분하세요.
2864 2864
2865**출력 (type: `"text"`):**2865**출력 (type: `"text"`):**
2866 2866
2869 "type": "text",2869 "type": "text",
2870 "file": {2870 "file": {
2871 "filePath": str, # 읽은 파일2871 "filePath": str, # 읽은 파일
2872 "content": str, # 반환된 콘텐츠2872 "content": str, # 반환된 내용
2873 "numLines": int, # 반환된 콘텐츠의 줄 수2873 "numLines": int, # 반환된 내용의 줄 수
2874 "startLine": int, # 콘텐츠가 시작되는 줄 번호2874 "startLine": int, # 내용이 시작되는 줄 번호
2875 "totalLines": int, # 파일의 총 줄 수2875 "totalLines": int, # 파일의 전체 줄 수
2876 "truncatedByTokenCap": bool | None, # 전체 파일 읽기가 토큰 상한을 초과했을 때 표시되고 True이며 콘텐츠는 첫 페이지입니다2876 "truncatedByTokenCap": bool | None, # 전체 파일 읽기가 토큰 상한을 초과하여 content가 첫 페이지인 경우 존재하며 True
2877 },2877 },
2878}2878}
2879```2879```
2888 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # 이미지 MIME 타입2888 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # 이미지 MIME 타입
2889 "originalSize": int, # 원본 파일 크기(바이트)2889 "originalSize": int, # 원본 파일 크기(바이트)
2890 "dimensions": { # 좌표 매핑을 위한 선택적 크기 정보2890 "dimensions": { # 좌표 매핑을 위한 선택적 크기 정보
2891 "originalWidth": int | None, # 선택적; 원본 너비(픽셀)2891 "originalWidth": int | None, # 선택 사항; 원본 너비(픽셀)
2892 "originalHeight": int | None, # 선택적; 원본 높이(픽셀)2892 "originalHeight": int | None, # 선택 사항; 원본 높이(픽셀)
2893 "displayWidth": int | None, # 선택적; 크기 조정 후 너비2893 "displayWidth": int | None, # 선택 사항; 크기 조정 후 너비
2894 "displayHeight": int | None, # 선택적; 크기 조정 후 높이2894 "displayHeight": int | None, # 선택 사항; 크기 조정 후 높이
2895 } | None,2895 } | None,
2896 },2896 },
2897}2897}
2931 "filePath": str, # 읽은 PDF2931 "filePath": str, # 읽은 PDF
2932 "originalSize": int, # 파일 크기(바이트)2932 "originalSize": int, # 파일 크기(바이트)
2933 "count": int, # 이미지로 추출된 페이지 수2933 "count": int, # 이미지로 추출된 페이지 수
2934 "outputDir": str, # 추출된 페이지 이미지를 포함하는 디렉토리2934 "outputDir": str, # 추출된 페이지 이미지가 있는 디렉터리
2935 },2935 },
2936 "firstPage": int | None, # 선택적 추출된 첫 페이지의 문서 페이지 번호2936 "firstPage": int | None, # 선택 사항; 첫 번째로 추출된 페이지의 문서 페이지 번호
2937}2937}
2938```2938```
2939 2939
2941 2941
2942```python theme={null}2942```python theme={null}
2943{2943{
2944 "type": "file_unchanged", # 파일은 Claude가 이 세션에서 마지막으로 읽은 이후 변경되지 않았으므로 콘텐츠가 반복되지 않습니다2944 "type": "file_unchanged", # 이 세션에서 Claude가 마지막으로 읽은 이후 파일이 변경되지 않았으므로 내용이 반복되지 않음
2945 "file": {2945 "file": {
2946 "filePath": str,2946 "filePath": str,
2947 },2947 },
2948 "source": "seeded" | None, # 이전 복사본이 Read 호출이 아닌 시작 시 로드된 CLAUDE.md 또는 메모리 파일에서 나온 경우 표시됨2948 "source": "seeded" | None, # 이전 사본이 Read 호출이 아닌 시작 시 로드된 CLAUDE.md 또는 메모리 파일에서 온 경우 존재
2949}2949}
2950```2950```
2951 2951
2958```python theme={null}2958```python theme={null}
2959{2959{
2960 "file_path": str, # 쓸 파일의 절대 경로2960 "file_path": str, # 쓸 파일의 절대 경로
2961 "content": str, # 파일에 쓸 콘텐츠2961 "content": str, # 파일에 쓸 내용
2962}2962}
2963```2963```
2964 2964
2966 2966
2967```python theme={null}2967```python theme={null}
2968{2968{
2969 "type": "create" | "update", # 쓰기가 새 파일을 생성했는지 또는 기존 파일을 덮어썼는지 여부2969 "type": "create" | "update", # 쓰기가 새 파일을 생성했는지 기존 파일을 덮어썼는지 여부
2970 "filePath": str, # 쓴 파일2970 "filePath": str, # 쓴 파일
2971 "content": str, # 쓴 콘텐츠2971 "content": str, # 쓴 내용
2972 "structuredPatch": [ # diff 청크; 새 파일, 아무것도 변경되지 않음, 또는 Claude Code가 diff를 건너뛴 경우 비어 있음2972 "structuredPatch": [ # diff 헝크; 새 파일인 경우, 변경 사항이 없는 경우, 또는 Claude Code가 diff를 건너뛴 경우 비어 있음
2973 {2973 {
2974 "oldStart": int,2974 "oldStart": int,
2975 "oldLines": int,2975 "oldLines": int,
2978 "lines": list[str],2978 "lines": list[str],
2979 }2979 }
2980 ],2980 ],
2981 "originalFile": str | None, # 이전 콘텐츠; 새 파일이거나 이전 콘텐츠가 너무 클 때 None2981 "originalFile": str | None, # 이전 내용; 새 파일이거나 이전 내용이 너무 커서 포함할 수 없는 경우 None
2982 "gitDiff": { # 파일에 대한 선택적 git diff 요약2982 "gitDiff": { # 파일에 대한 선택적 git diff 요약
2983 "filename": str,2983 "filename": str,
2984 "status": "modified" | "added",2984 "status": "modified" | "added",
2986 "deletions": int,2986 "deletions": int,
2987 "changes": int,2987 "changes": int,
2988 "patch": str,2988 "patch": str,
2989 "repository": str | None, # 사용 가능할 때 GitHub owner/repo2989 "repository": str | None, # 사용 가능한 경우 GitHub owner/repo
2990 } | None,2990 } | None,
2991 "userModified": bool | None, # 선택적; 사용자가 수락하기 전에 제안된 콘텐츠를 편집했는지 여부2991 "userModified": bool | None, # 선택 사항; 사용자가 수락하기 전에 제안된 내용을 편집했는지 여부
2992}2992}
2993```2993```
2994 2994
3001```python theme={null}3001```python theme={null}
3002{3002{
3003 "pattern": str, # 파일과 일치시킬 glob 패턴3003 "pattern": str, # 파일과 일치시킬 glob 패턴
3004 "path": str | None, # 검색할 디렉토리 (기본값은 cwd)3004 "path": str | None, # 검색할 디렉터리(기본값은 cwd)
3005}3005}
3006```3006```
3007 3007
3009 3009
3010```python theme={null}3010```python theme={null}
3011{3011{
3012 "durationMs": int, # 검색을 실행하는 데 걸린 시간(밀리초)3012 "durationMs": int, # 검색 실행에 걸린 시간(밀리초)
3013 "numFiles": int, # 반환된 경로 수, 모든 잘림 후3013 "numFiles": int, # 잘림 적용 후 반환된 경로 수
3014 "filenames": list[str], # 일치하는 파일 경로3014 "filenames": list[str], # 일치하는 파일 경로
3015 "truncated": bool, # 결과가 100파일 제한에서 잘렸는지 여부3015 "truncated": bool, # 결과가 100개 파일 제한에서 잘렸는지 여부
3016 "totalMatches": int | None, # 선택적 잘림 전 일치하는 파일의 총 수; countIsComplete가 False일 때 하한3016 "totalMatches": int | None, # 선택 사항; 잘림 전 일치하는 파일의 총 수; countIsComplete가 False인 경우 하한값
3017 "countIsComplete": bool | None, # 선택적; totalMatches가 정확한지 여부3017 "countIsComplete": bool | None, # 선택 사항; totalMatches가 정확한지 여부
3018}3018}
3019```3019```
3020 3020
3029```python theme={null}3029```python theme={null}
3030{3030{
3031 "pattern": str, # 정규 표현식 패턴3031 "pattern": str, # 정규 표현식 패턴
3032 "path": str | None, # 검색할 파일 또는 디렉토리3032 "path": str | None, # 검색할 파일 또는 디렉터리
3033 "glob": str | None, # 파일을 필터링할 glob 패턴3033 "glob": str | None, # 파일을 필터링할 glob 패턴
3034 "type": str | None, # 검색할 파일 타입3034 "type": str | None, # 검색할 파일 유형
3035 "output_mode": str | None, # "content", "files_with_matches" 또는 "count"3035 "output_mode": str | None, # "content", "files_with_matches" 또는 "count"
3036 "-i": bool | None, # 대소문자 구분 없는 검색3036 "-i": bool | None, # 대소문자 구분 없는 검색
3037 "-n": bool | None, # 줄 번호 표시3037 "-n": bool | None, # 줄 번호 표시
3038 "-B": int | None, # 각 일치 전에 표시할 줄3038 "-B": int | None, # 각 일치 항목 앞에 표시할 줄 수
3039 "-A": int | None, # 각 일치 후에 표시할 줄3039 "-A": int | None, # 각 일치 항목 뒤에 표시할 줄 수
3040 "-C": int | None, # 전후에 표시할 줄3040 "-C": int | None, # 앞뒤로 표시할 줄 수
3041 "context": int | None, # 전후에 표시할 줄; -C는 별칭3041 "context": int | None, # 앞뒤로 표시할 줄 수; -C는 별칭
3042 "-o": bool | None, # 각 줄의 일치한 부분만 인쇄3042 "-o": bool | None, # 각 줄에서 일치하는 부분만 출력
3043 "head_limit": int | None, # 출력을 처음 N개 줄/항목으로 제한3043 "head_limit": int | None, # 출력을 처음 N개 줄/항목으로 제한
3044 "offset": int | None, # head_limit을 적용하기 전에 처음 N개 줄/항목 건너뛰기3044 "offset": int | None, # head_limit 적용 전에 처음 N개 줄/항목 건너뛰기
3045 "multiline": bool | None, # 다중 줄 모드 활성화3045 "multiline": bool | None, # 여러 줄 모드 활성화
3046}3046}
3047```3047```
3048 3048
3051```python theme={null}3051```python theme={null}
3052{3052{
3053 "mode": "content" | "files_with_matches" | "count" | None, # 사용된 출력 모드3053 "mode": "content" | "files_with_matches" | "count" | None, # 사용된 출력 모드
3054 "numFiles": int, # 결과의 파일 수; 콘텐츠 모드에서는 항상 03054 "numFiles": int, # 결과에 포함된 파일 수; content 모드에서는 항상 0
3055 "filenames": list[str], # files_with_matches 모드의 일치하는 파일; 다른 모드에서는 비어 있음3055 "filenames": list[str], # files_with_matches 모드에서 일치하는 파일; 다른 모드에서는 비어 있음
3056 "content": str | None, # 콘텐츠 모드의 일치하는 줄, 또는 count 모드의 파일별 수3056 "content": str | None, # content 모드에서는 일치하는 줄, count 모드에서는 파일별 개수
3057 "numLines": int | None, # 콘텐츠의 줄 수, 콘텐츠 모드에 표시됨3057 "numLines": int | None, # content의 줄 수, content 모드에서 존재
3058 "numMatches": int | None, # 총 일치 수, count 모드에 표시됨3058 "numMatches": int | None, # 전체 일치 개수, count 모드에서 존재
3059 "totalFiles": int | None, # 선택적 head_limit과 offset 전 총 수, files_with_matches 모드3059 "totalFiles": int | None, # 선택 사항; head_limit 및 offset 적용 전 총계, files_with_matches 모드
3060 "totalLines": int | None, # 선택적 head_limit과 offset 전 총 수, 콘텐츠 모드3060 "totalLines": int | None, # 선택 사항; head_limit 및 offset 적용 전 총계, content 모드
3061 "appliedLimit": int | None, # head_limit이 결과를 잘랐을 때 표시됨3061 "appliedLimit": int | None, # head_limit으로 결과가 잘린 경우 존재
3062 "appliedOffset": int | None, # offset이 적용되었을 때 표시됨3062 "appliedOffset": int | None, # offset이 적용된 경우 존재
3063}3063}
3064```3064```
3065 3065
3066Grep은 각 출력 모드에서 이 dict 형태를 반환합니다. 어떤 선택적 키가 표시되는지는 `output_mode`에 따라 다릅니다.3066Grep은 모든 출력 모드에서 이 dict 형태를 반환합니다. 어떤 선택적 키가 존재하는지는 `output_mode`에 따라 달라집니다.
3067 3067
3068`totalFiles`는 Claude Code v2.1.208 이상이 필요합니다. `totalLines`는 Claude Code v2.1.210 이상이 필요합니다.3068`totalFiles`는 Claude Code v2.1.208 이상이 필요합니다. `totalLines`는 Claude Code v2.1.210 이상이 필요합니다.
3069 3069
3077{3077{
3078 "notebook_path": str, # Jupyter 노트북의 절대 경로3078 "notebook_path": str, # Jupyter 노트북의 절대 경로
3079 "cell_id": str | None, # 편집할 셀의 ID3079 "cell_id": str | None, # 편집할 셀의 ID
3080 "new_source": str, # 셀의 새로운 소스3080 "new_source": str, # 셀의 새 소스
3081 "cell_type": "code" | "markdown" | None, # 셀의 타입3081 "cell_type": "code" | "markdown" | None, # 셀의 유형
3082 "edit_mode": "replace" | "insert" | "delete" | None, # 편집 작업 타입3082 "edit_mode": "replace" | "insert" | "delete" | None, # 편집 작업 유형
3083}3083}
3084```3084```
3085 3085
3088```python theme={null}3088```python theme={null}
3089{3089{
3090 "new_source": str, # 셀에 쓴 소스3090 "new_source": str, # 셀에 쓴 소스
3091 "old_source": str | None, # 이전 셀 소스, replace와 delete에 표시됨3091 "old_source": str | None, # 이전 셀 소스, replace 및 delete에서 존재
3092 "cell_id": str | None, # 편집된 셀의 ID, 사용 가능할 때3092 "cell_id": str | None, # 사용 가능한 경우 편집된 셀의 ID
3093 "cell_type": "code" | "markdown", # 셀 타입3093 "cell_type": "code" | "markdown", # 셀 유형
3094 "language": str, # 노트북의 프로그래밍 언어3094 "language": str, # 노트북의 프로그래밍 언어
3095 "edit_mode": str, # 사용된 편집 모드3095 "edit_mode": str, # 사용된 편집 모드
3096 "error": str | None, # 작업이 실패했을 때 오류 메시지3096 "error": str | None, # 작업이 실패한 경우 오류 메시지
3097 "notebook_path": str, # 노트북 파일3097 "notebook_path": str, # 노트북 파일
3098 "original_file": str, # 편집 전 노트북 콘텐츠3098 "original_file": str, # 편집 전 노트북 내용
3099 "updated_file": str, # 편집 후 노트북 콘텐츠3099 "updated_file": str, # 편집 후 노트북 내용
3100}3100}
3101```3101```
3102 3102
3109```python theme={null}3109```python theme={null}
3110{3110{
3111 "url": str, # 콘텐츠를 가져올 URL3111 "url": str, # 콘텐츠를 가져올 URL
3112 "prompt": str, # 가져온 콘텐츠에서 실행할 프롬프트3112 "prompt": str, # 가져온 콘텐츠에 실행할 프롬프트
3113 "offset": int | None, # 페이지 시작 부분에서 건너뛸 문자 수. Python Agent SDK 0.2.164 이상 필요3113 "offset": int | None, # 페이지 시작 부분에서 건너뛸 문자 수. Python Agent SDK 0.2.164 이상 필요
3114}3114}
3115```3115```
3121 "bytes": int, # 가져온 콘텐츠의 크기(바이트)3121 "bytes": int, # 가져온 콘텐츠의 크기(바이트)
3122 "code": int, # HTTP 응답 코드3122 "code": int, # HTTP 응답 코드
3123 "codeText": str, # HTTP 응답 코드 텍스트3123 "codeText": str, # HTTP 응답 코드 텍스트
3124 "result": str, # 콘텐츠에 프롬프트를 적용한 처리된 결과3124 "result": str, # 콘텐츠에 프롬프트를 적용하여 처리한 결과
3125 "durationMs": int, # 콘텐츠를 가져오고 처리하는 데 걸린 시간(밀리초)3125 "durationMs": int, # 콘텐츠를 가져와 처리하는 데 걸린 시간(밀리초)
3126 "url": str, # 가져온 URL3126 "url": str, # 가져온 URL
3127}3127}
3128```3128```
3147{3147{
3148 "query": str, # 검색 쿼리3148 "query": str, # 검색 쿼리
3149 "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],3149 "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
3150 "durationSeconds": float, # 검색 시간(초)3150 "durationSeconds": float, # 검색 소요 시간(초)
3151}3151}
3152```3152```
3153 3153
3169>3169>
3170> 이 기본 집합은 Claude Code v2.1.268 이상에 적용되며, TypeScript Agent SDK는 v0.3.268부터 이를 번들로 제공합니다.3170> 이 기본 집합은 Claude Code v2.1.268 이상에 적용되며, TypeScript Agent SDK는 v0.3.268부터 이를 번들로 제공합니다.
3171>3171>
3172> [모델 가용성](https://code.claude.com/docs/ko/agent-sdk/todo-tracking.md#model-availability)을 참조하여 옵트인하십시오.3172> 옵트인하려면 [모델 사용 가능 여부](https://code.claude.com/docs/ko/agent-sdk/todo-tracking.md#model-availability)를 참조하세요.
3173 3173
3174**입력:**3174**입력:**
3175 3175
3179 {3179 {
3180 "content": str, # 작업 설명3180 "content": str, # 작업 설명
3181 "status": "pending" | "in_progress" | "completed", # 작업 상태3181 "status": "pending" | "in_progress" | "completed", # 작업 상태
3182 "activeForm": str, # 설명의 활성 형식3182 "activeForm": str, # 설명의 진행형
3183 }3183 }
3184 ]3184 ]
3185}3185}
3215```python theme={null}3215```python theme={null}
3216{3216{
3217 "subject": str, # 짧은 작업 제목3217 "subject": str, # 짧은 작업 제목
3218 "description": str, # 상세한 작업 본문3218 "description": str, # 자세한 작업 본문
3219 "activeForm": str | None, # 진행 중일 때 표시되는 현재형 레이블3219 "activeForm": str | None, # 진행 중에 표시되는 현재 진행형 레이블
3220 "metadata": dict | None, # 임의의 호출자 메타데이터3220 "metadata": dict | None, # 호출자가 지정하는 임의의 메타데이터
3221}3221}
3222```3222```
3223 3223
3225 3225
3226```python theme={null}3226```python theme={null}
3227{3227{
3228 "task": {"id": str, "subject": str}, # 할당된 ID가 있는 생성된 작업3228 "task": {"id": str, "subject": str}, # ID가 할당된 생성된 작업
3229}3229}
3230```3230```
3231 3231
3237 3237
3238```python theme={null}3238```python theme={null}
3239{3239{
3240 "taskId": str, # 패치할 작업의 ID3240 "taskId": str, # 수정할 작업의 ID
3241 "status": Literal["pending", "in_progress", "completed", "deleted"] | None,3241 "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
3242 "subject": str | None,3242 "subject": str | None,
3243 "description": str | None,3243 "description": str | None,
3255{3255{
3256 "success": bool,3256 "success": bool,
3257 "taskId": str,3257 "taskId": str,
3258 "updatedFields": list[str], # 변경된 필드의 이름3258 "updatedFields": list[str], # 변경된 필드 이름
3259 "error": str | None,3259 "error": str | None,
3260 "statusChange": {"from": str, "to": str} | None,3260 "statusChange": {"from": str, "to": str} | None,
3261}3261}
3284 "status": Literal["pending", "in_progress", "completed"],3284 "status": Literal["pending", "in_progress", "completed"],
3285 "blocks": list[str],3285 "blocks": list[str],
3286 "blockedBy": list[str],3286 "blockedBy": list[str],
3287 } | None, # ID를 찾을 수 없을 때 None3287 } | None, # ID를 찾을 수 없는 경우 None
3288}3288}
3289```3289```
3290 3290
3316 3316
3317### TaskOutput3317### TaskOutput
3318 3318
3319Claude Code v2.1.277에서 제거되었습니다. 이전에는 실행 중이거나 완료된 백그라운드 작업의 출력을 검색했으며, `BashOutput`은 별칭으로 허용되었습니다. 이제 Claude는 `Read`를 사용하여 백그라운드 작업의 출력 파일을 읽습니다.3319Claude Code v2.1.277에서 제거되었습니다. 이전에는 실행 중이거나 완료된 백그라운드 작업의 출력을 가져왔으며 `BashOutput`이 별칭으로 허용되었습니다. 이제 Claude는 대신 `Read`로 백그라운드 작업의 출력 파일을 읽습니다.
3320 3320
3321`disallowed_tools` 항목 또는 두 이름 중 하나를 여전히 지정하는 거부 규칙은 경고 없이 무시됩니다.3321두 이름 중 하나를 여전히 지정하는 `disallowed_tools` 항목이나 거부 규칙은 경고 없이 무시됩니다.
3322 3322
3323### TaskStop3323### TaskStop
3324 3324
3325**도구 이름:** `TaskStop`. 이전 이름 `KillShell`과 `KillBash`는 여전히 별칭으로 허용됩니다.3325**도구 이름:** `TaskStop`. 이전 이름인 `KillShell`과 `KillBash`는 권한 규칙, 훅 matcher, 그리고 `tools`, `allowed_tools`, `disallowed_tools` 옵션에서 계속 사용할 수 있습니다.
3326 3326
3327**입력:**3327**입력:**
3328 3328
3329```python theme={null}3329```python theme={null}
3330{3330{
3331 "task_id": str | None, # 중지할 백그라운드 작업의 ID3331 "task_id": str | None, # 중지할 백그라운드 작업의 ID
3332 "shell_id": str | None, # 더 이상 사용되지 않음: task_id를 대신 사용하십시오3332 "shell_id": str | None, # deprecated: 대신 task_id 사용
3333}3333}
3334```3334```
3335 3335
3339{3339{
3340 "message": str, # 작업에 대한 상태 메시지3340 "message": str, # 작업에 대한 상태 메시지
3341 "task_id": str, # 중지된 작업의 ID3341 "task_id": str, # 중지된 작업의 ID
3342 "task_type": str, # 중지된 작업의 타입3342 "task_type": str, # 중지된 작업의 유형
3343 "command": str | None, # 중지된 작업의 명령 또는 설명3343 "command": str | None, # 중지된 작업의 명령 또는 설명
3344}3344}
3345```3345```
3352 3352
3353```python theme={null}3353```python theme={null}
3354{3354{
3355 "plan": str # 사용자 승인을 위해 실행할 계획3355 "plan": str # 사용자 승인을 받기 위해 제시할 계획
3356}3356}
3357```3357```
3358 3358
3361```python theme={null}3361```python theme={null}
3362{3362{
3363 "plan": str | None, # 사용자에게 제시된 계획3363 "plan": str | None, # 사용자에게 제시된 계획
3364 "isAgent": bool, # 서브에이전트가 도구를 호출했을 때 True3364 "isAgent": bool, # 서브에이전트가 도구를 호출한 경우 True
3365 "filePath": str | None, # 계획이 파일에 저장되었을 때 표시됨3365 "filePath": str | None, # 계획이 파일에 저장된 경우 존재
3366 "hasTaskTool": bool | None, # 선택적; 현재 컨텍스트에서 Agent 도구를 사용할 수 있는지 여부3366 "hasTaskTool": bool | None, # 선택 사항; 현재 컨텍스트에서 Agent 도구를 사용할 수 있는지 여부
3367 "planWasEdited": bool | None, # 사용자가 승인하기 전에 계획을 편집했을 때 표시되고 True3367 "planWasEdited": bool | None, # 사용자가 승인 전에 계획을 편집한 경우 존재하며 True
3368 "awaitingLeaderApproval": bool | None, # 팀원이 팀 리더에게 승인을 위해 계획을 보냈을 때 표시되고 True3368 "awaitingLeaderApproval": bool | None, # 팀원이 승인을 위해 팀 리드에게 계획을 보낸 경우 존재하며 True
3369 "requestId": str | None, # 선택적 해당 승인 요청의 ID3369 "requestId": str | None, # 선택 사항; 해당 승인 요청의 ID
3370}3370}
3371```3371```
3372 3372
3382}3382}
3383```3383```
3384 3384
3385결과는 dict가 아닌 list이므로, `tool_use_result`는 이 도구에 대해 `list`를 보유합니다.3385결과는 dict가 아닌 list이므로, 이 도구의 `tool_use_result`는 `list`를 담습니다.
3386 3386
3387**출력:**3387**출력:**
3388 3388
3389```python theme={null}3389```python theme={null}
3390[ # 리소스당 하나의 항목3390[ # 리소스마다 하나의 항목
3391 {3391 {
3392 "uri": str, # 리소스 URI3392 "uri": str, # 리소스 URI
3393 "name": str, # 리소스 이름3393 "name": str, # 리소스 이름
3419 {3419 {
3420 "uri": str, # 리소스 URI3420 "uri": str, # 리소스 URI
3421 "mimeType": str | None, # 선택적 MIME 타입3421 "mimeType": str | None, # 선택적 MIME 타입
3422 "text": str | None, # 텍스트 콘텐츠, 또는 바이너리 콘텐츠에 대한 노트3422 "text": str | None, # 텍스트 콘텐츠 또는 바이너리 콘텐츠에 대한 안내
3423 "blobSavedTo": str | None, # Claude Code가 바이너리 콘텐츠를 디스크에 저장했을 때 표시됨; 저장된 파일의 경로3423 "blobSavedTo": str | None, # Claude Code가 바이너리 콘텐츠를 디스크에 저장한 경우 존재; 저장된 파일의 경로
3424 }3424 }
3425 ],3425 ],
3426 "error": str | None, # 서버가 리소스를 읽을 수 없을 때 표시됨3426 "error": str | None, # 서버가 리소스를 읽을 수 없는 경우 존재
3427}3427}
3428```3428```
3429 3429
