Documentation 2026-09-21 22:59 UTC to 2026-09-22 23:59 UTC

167 167 

168* [빠른 시작](/docs/ko/quickstart): 설치부터 프로젝트 작업까지의 첫 세션 안내168* [빠른 시작](/docs/ko/quickstart): 설치부터 프로젝트 작업까지의 첫 세션 안내

169* [일반적인 워크플로우](/docs/ko/common-workflows): 코드 검토, 리팩토링 및 디버깅과 같은 일상적인 작업의 패턴169* [일반적인 워크플로우](/docs/ko/common-workflows): 코드 검토, 리팩토링 및 디버깅과 같은 일상적인 작업의 패턴

170* [Claude 101](https://anthropic.skilljar.com/claude-101) 및 [Claude Code in Action](https://anthropic.skilljar.com/claude-code-in-action): 자기 주도식 Anthropic Academy 과정170* [Claude Code 101](https://academy.claude.com/courses/claude-code-101) 및 [Claude Code in Action](https://academy.claude.com/courses/claude-code-in-action): [Claude Academy](https://academy.claude.com/)의 무료 자기 주도식 과정

171 171 

172로그인 문제의 경우 개발자에게 [인증 문제 해결](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하도록 안내하세요. 가장 일반적인 해결 방법은 다음과 같습니다:172로그인 문제의 경우 개발자에게 [인증 문제 해결](/docs/ko/troubleshoot-install#login-and-authentication)을 참조하도록 안내하세요. 가장 일반적인 해결 방법은 다음과 같습니다:

173 173 

56* `/advisor opus`와 같이 모델을 사용하여 `/advisor`를 실행하여 설정합니다.56* `/advisor opus`와 같이 모델을 사용하여 `/advisor`를 실행하여 설정합니다.

57* `/advisor off`를 실행하여 끕니다.57* `/advisor off`를 실행하여 끕니다.

58 58 

59Claude Code는 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록이 제외하는 저장된 조언자를 호출하지 않습니다. 조언자를 사용하려면 `/advisor`로 허용된 모델을 선택하세요. Claude Code는 현재 주 모델이 지원하지 않는 조언자를 여전히 저장합니다. 해당 조언자는 [`/model`](/docs/ko/model-config#setting-your-model)을 사용하여 [호환되는 주 모델](#choose-an-advisor-model)로 전환한 후 활성화됩니다.59Claude Code는 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록이 제외하는 저장된 조언자를 호출하지 않습니다. 조언자를 사용하려면 `/advisor`로 허용된 모델을 선택하세요. Claude Code는 현재 주 모델이 지원하지 않는 조언자를 여전히 저장합니다. 해당 조언자는 [`/model`](/docs/ko/model-config#setting-your-model)을 사용하여 [호환되는 주 모델](#choose-an-advisor-model)로 전환한 후 활성화됩니다. API가 현재 대화에서 이미 저장된 조언자를 거부한 경우, 모델을 전환한 후에도 `/clear` 또는 `/compact`를 실행할 때까지 꺼진 상태로 유지됩니다. 일부 플랜에서 Fable을 조언자로 사용하려면 [Fable 사용량을 사용 크레딧으로 청구하는 것에 대한 일회성 동의](/docs/ko/model-config#fable-and-usage-credits)도 필요합니다. `/advisor fable`이 동의를 제공하기 전에 수행하는 작업에 대해서는 [Fable 조언자 및 사용 크레딧](#fable-advisor-and-usage-credits)을 참고하세요.

60 

61일부 플랜에서 Fable을 조언자로 사용하려면 [Fable 사용량을 사용 크레딧으로 청구하는 것에 대한 일회성 동의](/docs/ko/model-config#fable-and-usage-credits)도 필요합니다. `/advisor fable`이 동의를 제공하기 전에 수행하는 작업에 대해서는 [Fable 조언자 및 사용 크레딧](#fable-advisor-and-usage-credits)을 참고하세요.

62 60 

63<h3 id="set-advisormodel-in-settings">61<h3 id="set-advisormodel-in-settings">

64 설정에서 `advisorModel` 설정62 설정에서 `advisorModel` 설정

98조언자는 주 모델 이상의 기능을 가져야 합니다. 각 주 모델에 대해 허용되는 조언자는 다음과 같습니다:96조언자는 주 모델 이상의 기능을 가져야 합니다. 각 주 모델에 대해 허용되는 조언자는 다음과 같습니다:

99 97 

100| 주 모델 | 허용되는 조언자 | 참고 |98| 주 모델 | 허용되는 조언자 | 참고 |

101| -------------------- | ---------------------------- | ----------------------------------------------------------------------------- |99| -------------------- | ---------------------------- | ------------------------------------------------------------------ |

102| Haiku 4.5 | Fable, Opus, Sonnet | Haiku는 조언자를 호출할 수 있지만 조언자로 작동할 수 없습니다 |100| Haiku 4.5 | Fable, Opus, Sonnet | Haiku는 조언자를 호출할 수 있지만 조언자로 작동할 수 없습니다 |

103| Sonnet 4.6 | Fable, Opus, Sonnet | |101| Sonnet 4.6 | Fable, Opus, Sonnet | |

104| Sonnet 5 | Fable, Opus 4.7 이상, Sonnet 5 | Sonnet 4.6 조언자는 거부되며, Opus 4.6 조언자를 사용한 요청은 API 오류로 실패합니다 |102| Sonnet 5 | Fable, Opus 4.7 이상, Sonnet 5 | Sonnet 4.6 조언자는 거부되며, API는 Opus 4.6 조언자를 거부합니다 |

105| Opus 4.6 | Fable, Opus, Sonnet 5 | Sonnet 4.6 조언자는 거부됩니다 |103| Opus 4.6 | Fable, Opus, Sonnet 5 | Sonnet 4.6 조언자는 거부됩니다 |

106| Opus 4.7 또는 Opus 4.8 | Fable, Opus 4.7 이상 | Opus 4.6 또는 Sonnet 조언자는 거부됩니다 |104| Opus 4.7 또는 Opus 4.8 | Fable, Opus 4.7 이상 | Opus 4.6 또는 Sonnet 조언자는 거부됩니다 |

107| Opus 5 | Fable, Opus 5 | Opus 4.6 또는 Sonnet 조언자는 거부되며, Opus 4.7 또는 Opus 4.8 조언자를 사용한 요청은 API 오류로 실패합니다 |105| Opus 5.5 또는 Opus 5 | Fable, Opus 5 이상 | Opus 4.6 또는 Sonnet 조언자는 거부되며, API는 Opus 4.7 또는 Opus 4.8 조언자를 거부합니다 |

108| Fable 5 | Fable 5.1 또는 Fable 5 | Opus 또는 Sonnet 조언자는 거부됩니다 |106| Fable 5 | Fable 5.1 또는 Fable 5 | Opus 또는 Sonnet 조언자는 거부됩니다 |

109| Fable 5.1 | Fable 5.1 | Opus 또는 Sonnet 조언자는 거부되며, Fable 5 조언자를 사용한 요청은 API 오류로 실패합니다 |107| Fable 5.1 | Fable 5.1 | Opus 또는 Sonnet 조언자는 거부되며, API는 Fable 5 조언자를 거부합니다 |

110 108 

111Fable 5.1은 Claude Code v2.1.257 이상이 필요합니다. 둘 다 [Fable 액세스](/docs/ko/model-config#work-with-fable)가 필요합니다.109Fable 5.1은 Claude Code v2.1.257 이상이 필요합니다. 둘 다 [Fable 액세스](/docs/ko/model-config#work-with-fable)가 필요합니다.

112 110 

113조언자를 `fable`, `opus`, 또는 `sonnet`으로 설정하세요. 이러한 별칭은 Claude Code의 각 모델 제품군에 대한 기본 제공 기본 버전으로 확인되며, 새로운 Claude Code 릴리스와 함께 발전합니다. `claude-opus-5`와 같은 전체 모델 ID를 전달할 수도 있습니다.111조언자를 `fable`, `opus`, 또는 `sonnet`으로 설정하세요. 이러한 별칭은 Claude Code의 각 모델 제품군에 대한 기본 제공 기본 버전으로 확인되며, 새로운 Claude Code 릴리스와 함께 발전합니다. `claude-opus-5-5`와 같은 전체 모델 ID를 전달할 수도 있습니다.

114 112 

115하위 에이전트는 구성된 조언자를 상속하고 자신의 모델에 대해 동일한 쌍 확인을 적용합니다.113하위 에이전트는 구성된 조언자를 상속하고 자신의 모델에 대해 동일한 쌍 확인을 적용합니다.

116 114 

117Claude Code는 요청을 보내기 전에 쌍을 검증하며, API는 다시 한 번 검증합니다:115Claude Code는 요청을 보내기 전에 쌍을 검증하며, API는 다시 한 번 검증합니다:

118 116 

119* 표에서 거부된 것으로 나열된 조언자의 경우, Claude Code는 이를 주 모델의 요청에 첨부하지 않습니다. `/advisor` 명령 출력과 알림에 이것이 표시됩니다. 자신의 모델이 쌍 확인을 만족하는 하위 에이전트는 여전히 조언자를 사용할 수 있습니다.117* 표에서 거부된 것으로 나열된 조언자의 경우, Claude Code는 이를 주 모델의 요청에 첨부하지 않습니다. `/advisor` 명령 출력과 알림에 이것이 표시됩니다. 자신의 모델이 쌍 확인을 만족하는 하위 에이전트는 여전히 조언자를 사용할 수 있습니다.

120* 표에서 API 오류로 실패하는 것으로 나열된 조언자의 경우, Claude Code는 이를 첨부하고 API가 이를 거부합니다. 모든 요청이 `'<advisor model>'은(는) 요청 모델이 '<main model>'일 때 조언자로 사용될 수 없습니다`로 실패하며, `/advisor`로 조언자를 변경하거나 끌 때까지 계속됩니다.118* 표에서 API가 거부하는 것으로 나열된 조언자의 경우, Claude Code는 이를 첨부하고 API가 이를 거부합니다. Claude Code는 그 후 조언자 없이 해당 요청을 다시 보내며, 나머지 대화는 조언자 없이 실행되므로 오류가 표시되지 않고 조언자 호출이 없습니다. `/advisor`로 허용되는 조언자를 선택하세요. 변경 사항은 `/clear` 또는 `/compact` 후 및 새 세션에서 적용됩니다.

121* 주 모델 또는 조언자가 Claude Code가 인식하지 못하는 모델이면 조언자가 첨부되지 않습니다.119* 주 모델 또는 조언자가 Claude Code가 인식하지 못하는 모델이면 조언자가 첨부되지 않습니다.

122 120 

123<h3 id="fable-advisor-and-usage-credits">121<h3 id="fable-advisor-and-usage-credits">

195 193 

196조언자 도구는 다음 모두를 요구합니다:194조언자 도구는 다음 모두를 요구합니다:

197 195 

198* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. `ANTHROPIC_BASE_URL`로 구성된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다.196* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. `ANTHROPIC_BASE_URL`로 구성된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다. 게이트웨이 또는 그 업스트림이 조언자 도구를 인식하지 못하는 경우 Claude Code가 응답하는 방식에 대해 [자동 재시도 및 오류 전달](/docs/ko/llm-gateway-protocol#automatic-retry-and-error-forwarding)을 참조하십시오.

199* **지원되는 주 모델**: Fable, Opus 4.6 이상, Sonnet 4.6 이상 또는 Haiku 4.5. [조언자 모델 선택](#choose-an-advisor-model)을 참조하여 각 조언자가 어떤 모델을 지원하는지 확인하십시오.197* **지원되는 주 모델**: Fable, Opus 4.6 이상, Sonnet 4.6 이상 또는 Haiku 4.5. [조언자 모델 선택](#choose-an-advisor-model)을 참조하여 각 조언자가 어떤 모델을 지원하는지 확인하십시오.

200* **기능 플래그 가져오기**: Claude Code는 Anthropic에서 가져온 기능 플래그를 통해 조언자를 켭니다. `DISABLE_TELEMETRY`와 같이 플래그 가져오기를 끄는 변수가 설정된 세션에서는 조언자가 꺼진 상태로 유지됩니다. [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)을 참조하십시오.198* **기능 플래그 가져오기**: Claude Code는 Anthropic에서 가져온 기능 플래그를 통해 조언자를 켭니다. `DISABLE_TELEMETRY`와 같이 플래그 가져오기를 끄는 변수가 설정된 세션에서는 조언자가 꺼진 상태로 유지됩니다. [기능 플래그 가져오기가 필요한 기능](/docs/ko/env-vars#features-that-need-feature-flag-fetching)을 참조하십시오.

201 199 

189TypeScript는 또한 `applyFlagSettings()` 및 `updateSettings()`를 가집니다:189TypeScript는 또한 `applyFlagSettings()` 및 `updateSettings()`를 가집니다:

190 190 

191* **`applyFlagSettings()`**: `await session.applyFlagSettings({ effortLevel: "high" })`처럼 런타임에 설정을 적용합니다. 메서드는 옵션 필드가 아닌 설정 파일 키를 사용하므로 스키마 및 어떤 키가 세션 중에 적용되는지 [`applyFlagSettings()` 참조](/docs/ko/agent-sdk/typescript#applyflagsettings)를 확인하세요.191* **`applyFlagSettings()`**: `await session.applyFlagSettings({ effortLevel: "high" })`처럼 런타임에 설정을 적용합니다. 메서드는 옵션 필드가 아닌 설정 파일 키를 사용하므로 스키마 및 어떤 키가 세션 중에 적용되는지 [`applyFlagSettings()` 참조](/docs/ko/agent-sdk/typescript#applyflagsettings)를 확인하세요.

192* **`updateSettings()`**: `await session.updateSettings("localSettings", { outputStyle: "Explanatory" })`처럼 프로젝트의 로컬 설정 파일에 허용 목록에 있는 키 집합을 씁니다. 작성된 키는 세션의 다음 요청에서 적용되고 `local` 설정을 로드하는 나중 세션에 대해 지속됩니다. 메서드의 행은 [메서드 테이블](/docs/ko/agent-sdk/typescript#methods)에서 허용 목록에 있는 키 및 버전 하한을 지정합니다.192* **`updateSettings()`**: 허용 목록에 있는 키 하나를 설정 파일에 씁니다. [`updateSettings()` 참조](/docs/ko/agent-sdk/typescript#updatesettings)는 각 소스가 허용하는 키와 버전 하한을 지정합니다.

193 * 프로젝트의 로컬 설정 파일에 쓰려면 `"localSettings"`를 전달하세요. `await session.updateSettings("localSettings", { outputStyle: "Explanatory" })`처럼 사용합니다. 작성된 키는 세션의 다음 요청에서 적용되고 `local` 설정을 로드하는 나중 세션에 대해 지속됩니다.

194 * `"userSettings"`를 전달하여 해당 소스가 허용하는 유일한 키인 `effortLevel`을 씁니다. Claude Code는 이를 세션의 현재 모델에 대한 기본 노력 수준으로 저장하며, 실행 중인 세션의 노력은 변경되지 않습니다.

193 195 

194아래 예제는 2턴 세션을 실행하고 턴 사이에 구성을 변경하며 각 턴에 응답한 모델을 출력합니다. TypeScript에서 프롬프트 스트림은 설정자가 실행될 때까지 두 번째 메시지를 보유하며 두 번째 턴은 새 모델에서 실행됩니다.196아래 예제는 2턴 세션을 실행하고 턴 사이에 구성을 변경하며 각 턴에 응답한 모델을 출력합니다. TypeScript에서 프롬프트 스트림은 설정자가 실행될 때까지 두 번째 메시지를 보유하며 두 번째 턴은 새 모델에서 실행됩니다.

195 197 

37 37 

38* **`query()` 호출:** SDK의 `query()` 함수 한 번의 호출입니다. 단일 호출은 여러 단계를 포함할 수 있습니다: Claude가 응답하고, 도구를 사용하고, 결과를 얻고, 다시 응답합니다. 각 호출은 끝에 하나의 [`result`](/docs/ko/agent-sdk/typescript#sdkresultmessage) 메시지를 생성합니다. 단, [스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서는 하나의 `query()` 호출이 여러 사용자 턴을 수행하며 각 턴은 자신의 `result` 메시지를 내보냅니다.38* **`query()` 호출:** SDK의 `query()` 함수 한 번의 호출입니다. 단일 호출은 여러 단계를 포함할 수 있습니다: Claude가 응답하고, 도구를 사용하고, 결과를 얻고, 다시 응답합니다. 각 호출은 끝에 하나의 [`result`](/docs/ko/agent-sdk/typescript#sdkresultmessage) 메시지를 생성합니다. 단, [스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서는 하나의 `query()` 호출이 여러 사용자 턴을 수행하며 각 턴은 자신의 `result` 메시지를 내보냅니다.

39* **Step:** `query()` 호출 내의 단일 요청/응답 사이클입니다. 각 단계는 토큰 사용량이 있는 어시스턴트 메시지를 생성합니다.39* **Step:** `query()` 호출 내의 단일 요청/응답 사이클입니다. 각 단계는 토큰 사용량이 있는 어시스턴트 메시지를 생성합니다.

40* **Session:** 세션 ID로 연결된 일련의 `query()` 호출입니다(`resume` 옵션 사용). 세션 내의 각 `query()` 호출은 자신의 비용을 독립적으로 보고합니다.40* **Session:** 세션 ID로 연결된 일련의 `query()` 호출입니다(`resume` 옵션 사용). 재개된 호출의 결과는 해당 호출 자신의 비용이 아닌 세션 전체의 지출을 보고합니다. [여러 호출에 걸쳐 비용 누적하기](#accumulate-costs-across-multiple-calls)에서 합계가 어떻게 이월되는지 확인하십시오.

41 41 

42다음 다이어그램은 단일 `query()` 호출의 메시지 스트림을 보여주며, 각 단계에서 토큰 사용량이 보고되고 끝에 누적 추정치가 표시됩니다:42다음 다이어그램은 단일 `query()` 호출의 메시지 스트림을 보여주며, 각 단계에서 토큰 사용량이 보고되고 끝에 누적 추정치가 표시됩니다:

43 43 

51 </Step>51 </Step>

52 52 

53 <Step title="결과 메시지는 누적 추정치를 제공합니다">53 <Step title="결과 메시지는 누적 추정치를 제공합니다">

54 `query()` 호출이 완료되면, SDK는 `total_cost_usd` 및 누적 `usage`가 있는 결과 메시지를 내보냅니다. TypeScript에서는 [`SDKResultMessage`](/docs/ko/agent-sdk/typescript#sdkresultmessage)로 입력되고 Python에서는 [`ResultMessage`](/docs/ko/agent-sdk/python#resultmessage)로 입력됩니다. 예를 들어 다중 턴 세션에서 여러 `query()` 호출을 수행하는 경우, 각 결과는 해당 개별 호출의 비용만 반영합니다. 추정 합계만 필요한 경우, 단계별 사용량을 무시하고 이 단일 값을 읽을 수 있습니다.54 `query()` 호출이 완료되면, SDK는 `total_cost_usd` 및 누적 `usage`가 있는 결과 메시지를 내보냅니다. TypeScript에서는 [`SDKResultMessage`](/docs/ko/agent-sdk/typescript#sdkresultmessage)로 입력되고 Python에서는 [`ResultMessage`](/docs/ko/agent-sdk/python#resultmessage)로 입력됩니다. 예상 합계만 필요한 경우, 단계별 사용량을 무시하고 이 단일 값을 읽을 수 있습니다.

55 

56 여러 개의 독립적인 `query()` 호출을 수행하는 경우, 각 결과는 해당 개별 호출의 비용만 반영합니다. 세션을 재개하는 호출도 세션의 이전 지출을 계산합니다.

55 57 

56 스트리밍 입력 모드에서는 각 턴이 자신의 결과 메시지를 내보냅니다. 해당 모드에서 호출 합계를 읽는 방법은 [스트리밍 입력 모드에서 비용 추적](#track-costs-in-streaming-input-mode)을 참조하십시오.58 스트리밍 입력 모드에서는 각 턴이 자신의 결과 메시지를 내보냅니다. 해당 모드에서 호출 합계를 읽는 방법은 [스트리밍 입력 모드에서 비용 추적](#track-costs-in-streaming-input-mode)을 참조하십시오.

57 </Step>59 </Step>

64[스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서 하나의 `query()` 호출은 여러 사용자 턴을 포함하며 각 턴은 자신의 결과 메시지를 내보냅니다. 결과 필드는 범위가 다릅니다:66[스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서 하나의 `query()` 호출은 여러 사용자 턴을 포함하며 각 턴은 자신의 결과 메시지를 내보냅니다. 결과 필드는 범위가 다릅니다:

65 67 

66* **`usage`**: 해당 턴만 포함하며, 그 내에서도 주 에이전트 루프만 포함하고 실행한 서브에이전트는 포함하지 않습니다.68* **`usage`**: 해당 턴만 포함하며, 그 내에서도 주 에이전트 루프만 포함하고 실행한 서브에이전트는 포함하지 않습니다.

67* **`total_cost_usd` 및 `modelUsage`, 또는 Python의 `model_usage`**: 지금까지 전체 호출에 대한 누적 합계를 나타냅니다.69* **`total_cost_usd` 및 `modelUsage`, 또는 Python의 `model_usage`**: 지금까지 전체 호출에 대한 누적 합계를 나타내며, 호출이 세션을 재개할 때 복원된 모든 지출을 포함합니다.

68 70 

69앱이 `/clear`, `/reset`, 또는 `/new`를 보내지 않는 호출에서는 결과 전체를 합산하는 대신 최신 결과에서 호출 합계를 읽습니다.71앱이 `/clear`, `/reset`, 또는 `/new`를 보내지 않는 호출에서는 결과 전체를 합산하는 대신 최신 결과에서 호출 합계를 읽습니다.

70 72 

78 80 

79TypeScript에서 SDK는 각 재설정 시 [`SDKConversationResetMessage`](/docs/ko/agent-sdk/typescript#sdkconversationresetmessage)도 내보내므로 스트림에서 재설정을 감지할 수 있습니다. Python에서 SDK는 마찬가지로 `ConversationResetMessage`를 내보냅니다. Python SDK v0.2.137 이전에는 Python 반복자가 해당 메시지를 삭제했으므로 해당 버전에서는 앱이 보내는 `/clear` 턴에서 재설정을 직접 계산합니다.81TypeScript에서 SDK는 각 재설정 시 [`SDKConversationResetMessage`](/docs/ko/agent-sdk/typescript#sdkconversationresetmessage)도 내보내므로 스트림에서 재설정을 감지할 수 있습니다. Python에서 SDK는 마찬가지로 `ConversationResetMessage`를 내보냅니다. Python SDK v0.2.137 이전에는 Python 반복자가 해당 메시지를 삭제했으므로 해당 버전에서는 앱이 보내는 `/clear` 턴에서 재설정을 직접 계산합니다.

80 82 

81`maxBudgetUsd`, 또는 Python의 `max_budget_usd`는 동일한 누적 합계와 비교되므로 `/clear`도 예산을 다시 시작합니다.83`maxBudgetUsd`(TypeScript) 또는 `max_budget_usd`(Python)는 호출 자체의 지출만 계산합니다: 재개된 세션에서 복원된 합계는 이에 대해 계산되지 않으며, `/clear`는 예산을 다시 시작합니다.

82 84 

83<h2 id="get-the-total-cost-of-a-query">85<h2 id="get-the-total-cost-of-a-query">

84 쿼리의 총 비용 얻기86 쿼리의 총 비용 얻기

85</h2>87</h2>

86 88 

87결과 메시지는 TypeScript에서 [`SDKResultMessage`](/docs/ko/agent-sdk/typescript#sdkresultmessage)로, Python에서 [`ResultMessage`](/docs/ko/agent-sdk/python#resultmessage)로 타입이 지정되며, `query()` 호출에 대한 에이전트 루프의 끝을 표시합니다. 이 메시지에는 해당 호출의 모든 단계에 걸친 누적 예상 비용인 `total_cost_usd`가 포함됩니다. Python에서는 이 필드가 선택적으로 타입이 지정되므로, 읽기 전에 `None`이 아닌지 확인하십시오. 성공 및 오류 결과 모두 이를 포함하지만, [세션 충돌](#recover-totals-after-a-session-crash) 후의 최종 결과는 이를 0으로 포함할 수 있습니다.89결과 메시지는 TypeScript에서 [`SDKResultMessage`](/docs/ko/agent-sdk/typescript#sdkresultmessage)로, Python에서 [`ResultMessage`](/docs/ko/agent-sdk/python#resultmessage)로 타입이 지정되며, `query()` 호출에 대한 에이전트 루프의 끝을 표시합니다. 이 메시지에는 해당 호출의 모든 단계에 걸친 누적 예상 비용인 `total_cost_usd`가 포함됩니다. 세션을 재개하는 호출도 세션의 이전 지출을 계산합니다. 값을 읽을 때 두 가지 주의사항이 적용됩니다:

90 

91* Python에서는 필드가 선택적으로 타입이 지정되므로, 읽기 전에 `None`이 아닌지 확인하십시오.

92* 성공 및 오류 결과 모두 이를 포함하지만, [세션 충돌](#recover-totals-after-a-session-crash) 후의 최종 결과는 이를 0으로 포함할 수 있습니다.

88 93 

89세션을 사용하여 여러 `query()` 호출을 수행하는 경우, 각 결과는 해당 개별 호출의 비용만 반영합니다. 스트리밍 입력 모드에서는 [스트리밍 입력 모드에서 비용 추적](#track-costs-in-streaming-input-mode)에 설명된 대로 호출 총액을 읽으십시오.94스트리밍 입력 모드에서는 [스트리밍 입력 모드에서 비용 추적](#track-costs-in-streaming-input-mode)에 설명된 대로 호출 총액을 읽으십시오.

90 95 

91세 가지 결과 수준 필드는 에이전트가 [서브에이전트](/docs/ko/agent-sdk/subagents)를 생성할 때 계산하는 내용이 다릅니다. 전체 트리 토큰 회계를 위해 `modelUsage` 또는 Python의 `model_usage`를 사용하십시오. `usage` 필드는 중첩이 발생하는 즉시 과소 계산됩니다.96세 가지 결과 수준 필드는 에이전트가 [서브에이전트](/docs/ko/agent-sdk/subagents)를 생성할 때 계산하는 내용이 다릅니다. 전체 트리 토큰 회계를 위해 `modelUsage` 또는 Python의 `model_usage`를 사용하십시오. `usage` 필드는 중첩이 발생하는 즉시 과소 계산됩니다.

92 97 

232 여러 호출에 걸쳐 비용 누적하기237 여러 호출에 걸쳐 비용 누적하기

233</h2>238</h2>

234 239 

235각 `query()` 호출은 자체 `total_cost_usd`를 반환합니다. SDK는 세션 수준의 총합을 제공하지 않으므로, 애플리케이션이 여러 `query()` 호출을 수행하는 경우(예: 다중 턴 세션 또는 여러 사용자에 걸쳐), 총합을 직접 누적해야 합니다. 스트리밍 입력 모드에서는 [스트리밍 입력 모드에서 비용 추적하기](#track-costs-in-streaming-input-mode)에 설명된 대로 각 호출의 총합을 읽으십시오. 충돌로 끝난 호출의 경우 [세션 충돌 후 총합 복구하기](#recover-totals-after-a-session-crash)를 참조하십시오.240각 `query()` 호출은 자체 결과에서 `total_cost_usd`를 반환합니다. 값을 결합하는 방식은 호출이 세션을 공유하는지 여부에 따라 달라집니다:

241 

242* **독립적인 호출, `resume` 또는 `continue` 옵션 없음**: 각 결과는 자체 호출만 포함하므로, 아래 예제처럼 총합을 직접 더해야 합니다.

243* **동일한 세션을 재개하는 호출**: Claude Code는 프로세스가 정상적으로 종료될 때 세션의 총합을 [트랜스크립트](/docs/ko/sessions#where-transcripts-are-stored)에 저장하고, 나중에 호출이 세션을 재개하거나 포크할 때 복구합니다. 각 결과는 이미 세션의 이전 지출을 포함합니다. 세션 총합을 위해 최신 결과를 읽으십시오. 결과를 합산하면 복구된 지출이 중복 계산됩니다. v2.1.277 이전에는 SDK 또는 `claude -p`를 통해 재개한 세션이 총합을 0에서 시작했으므로, 각 호출의 결과는 해당 호출만 포함했습니다.

244 

245스트리밍 입력 모드에서는 [스트리밍 입력 모드에서 비용 추적하기](#track-costs-in-streaming-input-mode)에 설명된 대로 각 호출의 총합을 읽으십시오. 충돌로 끝난 호출의 경우 [세션 충돌 후 총합 복구하기](#recover-totals-after-a-session-crash)를 참조하십시오.

236 246 

237다음 예제는 두 개의 `query()` 호출을 순차적으로 실행하고, 각 호출의 `total_cost_usd`를 누적 총합에 더하며, 호출별 비용과 결합된 비용을 모두 출력합니다:247다음 예제는 두 개의 `query()` 호출을 순차적으로 실행하고, 각 호출의 `total_cost_usd`를 누적 총합에 더하며, 호출별 비용과 결합된 비용을 모두 출력합니다:

238 248 

338 348 

339Claude Code 프로세스가 충돌하면 최종 `error_during_execution` 결과를 내보내고 종료합니다. 단일 샷 및 스트리밍 입력 모드 모두에서 그렇습니다. 해당 결과는 0으로 설정된 `usage`, `total_cost_usd` 및 `modelUsage`를 포함할 수 있으므로, 이전에 도착한 것에서 호출의 합계를 복구합니다. 1단계는 이전 결과가 존재할 때마다 전체 합계를 복구합니다. 2단계의 폴백은 메인 루프의 입력 및 캐시 토큰만 복구합니다.349Claude Code 프로세스가 충돌하면 최종 `error_during_execution` 결과를 내보내고 종료합니다. 단일 샷 및 스트리밍 입력 모드 모두에서 그렇습니다. 해당 결과는 0으로 설정된 `usage`, `total_cost_usd` 및 `modelUsage`를 포함할 수 있으므로, 이전에 도착한 것에서 호출의 합계를 복구합니다. 1단계는 이전 결과가 존재할 때마다 전체 합계를 복구합니다. 2단계의 폴백은 메인 루프의 입력 및 캐시 토큰만 복구합니다.

340 350 

3411. 충돌 전 턴의 결과를 사용합니다. 스트리밍 입력 모드에서는 호출 시작 이후 또는 마지막 [`/clear`](#track-costs-in-streaming-input-mode) 이후의 누적 합계를 포함합니다. 해당 결과가 도움이 될 수 없을 때 2단계로 이동합니다:3511. 충돌 전 턴의 결과를 사용합니다. 스트리밍 입력 모드에서는 [스트리밍 입력 모드에서 비용 추적](#track-costs-in-streaming-input-mode)에 설명된 누적 합계를 포함합니다. 해당 결과가 도움이 될 수 없을 때 2단계로 이동합니다:

342 * 호출이 단일 샷이므로 이전 결과가 없습니다.352 * 호출이 단일 샷이므로 이전 결과가 없습니다.

343 * 충돌이 첫 번째 턴에서 발생했습니다.353 * 충돌이 첫 번째 턴에서 발생했습니다.

344 * 충돌 전 턴이 `/clear` 자체였으므로, 그 결과는 재설정만 포함합니다.354 * 충돌 전 턴이 `/clear` 자체였으므로, 그 결과는 재설정만 포함합니다.

10 10 

11이 페이지는 자체 인프라에서의 자체 호스팅을 다룹니다. 배포 가능한 Dockerfile 및 Kubernetes 매니페스트는 [호스팅 쿡북](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting)을 참조하십시오.11이 페이지는 자체 인프라에서의 자체 호스팅을 다룹니다. 배포 가능한 Dockerfile 및 Kubernetes 매니페스트는 [호스팅 쿡북](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting)을 참조하십시오.

12 12 

13인프라 제어, 사용자 정의 격리 또는 자체 데이터 플레인이 필요하지 않은 경우 [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)를 대신 고려하십시오: Anthropic이 에이전트와 샌드박스를 실행하는 호스팅된 REST API이므로 애플리케이션은 이벤트를 보내고 호스팅 인프라를 운영할 필요 없이 결과를 다시 스트리밍합니다.13에이전트 루프를 자체 인프라에서 실행할 필요가 없는 경우 [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)를 대신 고려하십시오. Anthropic이 에이전트 루프를 호스팅하며, 애플리케이션은 클라이언트 SDK 또는 REST API를 통해 이벤트를 보내고 스트리밍된 결과를 수신합니다. 도구 실행은 Anthropic 관리 클라우드 샌드박스 또는 자체 인프라의 [자체 호스팅 샌드박스](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes)에서 실행됩니다.

14 14 

15<h2 id="the-subprocess-model">15<h2 id="the-subprocess-model">

16 서브프로세스 모델16 서브프로세스 모델

387* 마커를 두 번 이상 포함하면, 첫 번째가 분할이고 SDK는 나머지를 제거합니다.387* 마커를 두 번 이상 포함하면, 첫 번째가 분할이고 SDK는 나머지를 제거합니다.

388* 마커를 생략하면, SDK는 모든 문자열을 하나의 블록으로 조인하며, 이는 하나의 문자열을 전달하는 것과 같습니다.388* 마커를 생략하면, SDK는 모든 문자열을 하나의 블록으로 조인하며, 이는 하나의 문자열을 전달하는 것과 같습니다.

389 389 

390CLI의 [`--system-prompt` 또는 `--system-prompt-file` 플래그](/docs/ko/cli-reference#system-prompt-flags)를 사용하면, 프롬프트는 하나의 문자열이므로 마커를 전달할 배열이 없습니다. 정적 부분과 요청별 부분 사이에 `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__`만 포함된 줄을 포함하십시오. Claude Code는 프롬프트를 첫 번째 줄에서 동일한 두 블록으로 분할하고 해당 줄을 제거합니다. Claude Code v2.1.275 이상이 필요합니다.

391 

392SDK에서는 배열 형식을 선호하십시오. 이는 마커 줄 없이 경계를 전달합니다.

393 

390<h3 id="change-the-prompt-of-an-existing-session">394<h3 id="change-the-prompt-of-an-existing-session">

391 기존 세션의 프롬프트 변경395 기존 세션의 프롬프트 변경

392</h3>396</h3>

12 Agent SDK를 다른 Claude 도구와 비교12 Agent SDK를 다른 Claude 도구와 비교

13</h2>13</h2>

14 14 

15Agent SDK, CLI, Client SDK, Managed Agents는 각각 다른 요구사항에 맞습니다. 구축 중인 것에 맞는 도구를 찾으려면 표를 사용하십시오.15Agent SDK, CLI, Client SDK, Managed Agents는 에이전트를 누가 실행하는지, 무엇이 기본으로 제공되는지, 어떻게 접근하는지에 따라 다릅니다. 에이전트를 구축하고 실행하려는 방식과 일치하는 행을 찾으십시오.

16 16 

17| 다음의 경우... | 사용 | 이유 |17| 원하는 작업 | 사용 | 제공되는 것 |

18| ------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------- |18| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

19| 도구 루프를 직접 구현하지 않고 에이전트를 구축하는 경우 | **Agent SDK** | Python 또는 TypeScript에서 자신의 프로세스에서 에이전트 루프를 실행하는 라이브러리입니다. |19| Claude Code의 에이전트를 자신이 운영하는 프로세스에서 자신의 Python 또는 TypeScript 애플리케이션에 포함시키기 | **Agent SDK** | Claude Code 바이너리를 실행하는 라이브러리로, 기본 제공 도구, 권한, 세션, 훅 등 Claude Code의 [기능](#capabilities)을 포함합니다. |

20| 터미널에서 대화형 개발을 수행하거나 일회성 작업을 실행하는 경우 | [**Claude Code CLI**](/docs/ko/overview) | 일일 대화형 사용을 위해 구축된 터미널 인터페이스입니다. |20| 터미널에서 대화형 개발을 수행하거나 일회성 작업 실행 | [**Claude Code CLI**](/docs/ko/overview) | 일일 대화형 사용을 위해 구축된 터미널 인터페이스입니다. |

21| API를 직접 호출하고 도구 루프를 직접 구현하는 경우 | [**Client SDK**](https://platform.claude.com/docs/en/api/client-sdks) | Claude Code가 아닌 Anthropic API에 직접 액세스합니다. 도구 루프를 직접 구현합니다. |21| 자신의 코드에서 Claude API를 직접 호출 | [**Client SDK**](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) | 모든 Client SDK 언어에서 Claude API에 직접 액세스합니다. 도구 루프를 직접 작성하거나 Client SDK의 베타 [도구 실행기](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner)가 이를 구동하도록 할 수 있습니다. |

22| 자신의 샌드박스 또는 세션 인프라를 관리하지 않고 장기 실행 또는 비동기 에이전트를 실행하는 경우 | [**Managed Agents**](https://platform.claude.com/docs/en/managed-agents/overview) | 호스팅된 REST API로, Agent SDK와는 별개의 제품입니다. Anthropic이 에이전트와 샌드박스를 실행합니다. |22| Anthropic이 에이전트를 호스팅하고 Claude API를 통해 구성 | [**Managed Agents**](https://platform.claude.com/docs/en/managed-agents/overview) | 에이전트 루프를 실행하는 호스팅된 에이전트 하네스로, Anthropic 관리 클라우드 샌드박스 또는 자신의 인프라에 있는 [자체 호스팅 샌드박스](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes)의 세션을 포함합니다. [자신의 언어용 SDK](https://platform.claude.com/docs/en/managed-agents/quickstart#install-the-sdk), `ant` CLI 또는 REST API에서 사용합니다. |

23 23 

24SDK는 Python 및 TypeScript용 라이브러리로만 사용 가능합니다. 다른 언어에서 동일한 에이전트 루프를 실행하려면 `-p` 플래그 및 `--output-format json`과 함께 [CLI를 서브프로세스로 실행](/docs/ko/headless)하십시오.24Python 또는 TypeScript 이외의 언어에서 동일한 에이전트 루프를 구동하려면 `-p` 플래그 및 `--output-format json`과 함께 [CLI를 서브프로세스로 실행](/docs/ko/headless)하십시오.

25 25 

26<h2 id="capabilities">26<h2 id="capabilities">

27 기능27 기능

905| `resume` | `str \| None` | `None` | 재개할 세션 ID |905| `resume` | `str \| None` | `None` | 재개할 세션 ID |

906| `session_id` | `str \| None` | `None` | 자동 생성된 세션 ID 대신 특정 세션 ID를 사용합니다. 유효한 UUID여야 합니다. `fork_session`도 설정되지 않으면 `continue_conversation` 또는 `resume`과 결합할 수 없습니다 |906| `session_id` | `str \| None` | `None` | 자동 생성된 세션 ID 대신 특정 세션 ID를 사용합니다. 유효한 UUID여야 합니다. `fork_session`도 설정되지 않으면 `continue_conversation` 또는 `resume`과 결합할 수 없습니다 |

907| `max_turns` | `int \| None` | `None` | 최대 에이전트 턴 (도구 사용 왕복) |907| `max_turns` | `int \| None` | `None` | 최대 에이전트 턴 (도구 사용 왕복) |

908| `max_budget_usd` | `float \| None` | `None` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리 중지. `total_cost_usd`와 동일한 추정과 비교됨. 정확도 주의 사항 및 재설정 동작은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking) 참조 |908| `max_budget_usd` | `float \| None` | `None` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리 중지. 호출 자체의 지출만 계산합니다. 재개된 세션에서 복원된 총액은 계산되지 않습니다. 정확도 주의 사항 및 재설정 동작은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking) 참조 |

909| `disallowed_tools` | `list[str]` | `[]` | 거부할 도구. `"Bash"`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `"Bash(rm *)"` 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [작성된 대로 명령](/docs/ko/permissions#bash-rule-limits)에 대해 [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |909| `disallowed_tools` | `list[str]` | `[]` | 거부할 도구. `"Bash"`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `"Bash(rm *)"` 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [작성된 대로 명령](/docs/ko/permissions#bash-rule-limits)에 대해 [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

910| `enable_file_checkpointing` | `bool` | `False` | 되감기를 위한 파일 변경 추적 활성화. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |910| `enable_file_checkpointing` | `bool` | `False` | 되감기를 위한 파일 변경 추적 활성화. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |

911| `model` | `str \| None` | `None` | Claude 모델 별칭 또는 전체 모델 이름. [허용되는 값 및 공급자별 ID](/docs/ko/model-config#available-models) 참조 |911| `model` | `str \| None` | `None` | Claude 모델 별칭 또는 전체 모델 이름. [허용되는 값 및 공급자별 ID](/docs/ko/model-config#available-models) 참조 |

1487`ClaudeAgentOptions`의 `betas` 필드와 함께 사용하여 베타 기능을 활성화합니다.1487`ClaudeAgentOptions`의 `betas` 필드와 함께 사용하여 베타 기능을 활성화합니다.

1488 1488 

1489<Warning>1489<Warning>

1490 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 헤더를 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, 또는 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)로 마이그레이션하십시오. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.1490 `context-1m-2025-08-07` 베타는 2026년 4월 30일부터 폐기되었습니다. Claude Sonnet 4.5 또는 Sonnet 4와 함께 이 헤더를 전달하면 효과가 없으며, 표준 200k 토큰 컨텍스트 윈도우를 초과하는 요청은 오류를 반환합니다. 1M 토큰 컨텍스트 윈도우를 사용하려면 [Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, 또는 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)로 마이그레이션하십시오. 이들은 베타 헤더 없이 표준 가격으로 1M 컨텍스트를 포함합니다.

1491</Warning>1491</Warning>

1492 1492 

1493<h3 id="mcpsdkserverconfig">1493<h3 id="mcpsdkserverconfig">

1799 1799 

1800`model_usage` dict는 모델 이름을 모델별 사용량에 매핑합니다. 이는 쿼리 파이프라인을 통해 수행된 모든 모델 호출을 포함합니다: 주 루프, 서브에이전트 및 압축 및 Workflow 에이전트와 같은 내부 호출입니다. 권한 분류기 및 토큰 계산 요청과 같은 해당 파이프라인 외부의 도우미 호출은 `model_usage`에서 제외됩니다. `model_usage`를 추정치로 취급하며, 청구 명세서가 아닙니다.1800`model_usage` dict는 모델 이름을 모델별 사용량에 매핑합니다. 이는 쿼리 파이프라인을 통해 수행된 모든 모델 호출을 포함합니다: 주 루프, 서브에이전트 및 압축 및 Workflow 에이전트와 같은 내부 호출입니다. 권한 분류기 및 토큰 계산 요청과 같은 해당 파이프라인 외부의 도우미 호출은 `model_usage`에서 제외됩니다. `model_usage`를 추정치로 취급하며, 청구 명세서가 아닙니다.

1801 1801 

1802[스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서 `model_usage`와 `total_cost_usd`는 턴 전체에 누적되므로 결과 전체를 합산하는 대신 최신 결과를 읽으십시오. 재설정은 [스트리밍 입력 모드에서 비용 추적](/docs/ko/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)을 참조하고 0으로 설정된 결과는 [세션 충돌 후 합계 복구](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)를 참조하십시오.1802[스트리밍 입력 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)에서 `model_usage`와 `total_cost_usd`는 턴 전체에 누적되므로 결과 전체를 합산하는 대신 최신 결과를 읽으십시오. 세션을 재설정하면 [세션의 이전 호출에서 복원된 합계](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)도 계산됩니다. 재설정이 실행 합계에 미치는 영향은 [스트리밍 입력 모드에서 비용 추적](/docs/ko/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)을 참조하고 0으로 설정된 결과는 [세션 충돌 후 합계 복구](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)를 참조하십시오.

1803 1803 

1804`model_usage`의 각 값은 `from claude_agent_sdk.types import ModelUsage`를 통해 가져온 `ModelUsage` TypedDict입니다. 해당 키는 기본 CLI 프로세스에서 수정되지 않은 상태로 전달되는 값과 일치하는 TypeScript [`ModelUsage`](/docs/ko/agent-sdk/typescript#modelusage) 타입과 일치하므로 camelCase를 사용합니다:1804`model_usage`의 각 값은 `from claude_agent_sdk.types import ModelUsage`를 통해 가져온 `ModelUsage` TypedDict입니다. 해당 키는 기본 CLI 프로세스에서 수정되지 않은 상태로 전달되는 값과 일치하는 TypeScript [`ModelUsage`](/docs/ko/agent-sdk/typescript#modelusage) 타입과 일치하므로 camelCase를 사용합니다:

1805 1805 

2923 "command": str | None, # 셸 스크립트; 각 stdout 줄은 이벤트이고, 종료는 감시를 끝냅니다2923 "command": str | None, # 셸 스크립트; 각 stdout 줄은 이벤트이고, 종료는 감시를 끝냅니다

2924 "ws": dict | None, # WebSocket 소스: {"url": str, "protocols": list[str] | None}; 각 텍스트 프레임은 이벤트입니다2924 "ws": dict | None, # WebSocket 소스: {"url": str, "protocols": list[str] | None}; 각 텍스트 프레임은 이벤트입니다

2925 "description": str, # 알림에 표시되는 짧은 설명2925 "description": str, # 알림에 표시되는 짧은 설명

2926 "timeout_ms": int | None, # 이 기한 후 종료 (기본값 300000, 최대 3600000)2926 "timeout_ms": int | None, # 이 기한 후 종료 (기본값 300000, 최대 3600000; 유효한 기한은 최대 1800000)

2927 "persistent": bool | None, # 세션의 수명 동안 실행; TaskStop으로 중지

2928}2927}

2929```2928```

2930 2929 

2933```python theme={null}2932```python theme={null}

2934{2933{

2935 "taskId": str, # 백그라운드 모니터 작업의 ID2934 "taskId": str, # 백그라운드 모니터 작업의 ID

2936 "timeoutMs": int, # 밀리초 단위의 시간 초과 기한 (지속적일 때 0)2935 "timeoutMs": int, # 밀리초 단위의 감시 유효 기한

2937 "persistent": bool | None, # TaskStop 또는 세션 종료까지 실행 중일 때 True2936 "persistent": bool | None, # False: 모든 감시에는 기한이 있습니다

2938}2937}

2939```2938```

2940 2939 

3350 TaskOutput3349 TaskOutput

3351</h3>3350</h3>

3352 3351 

3353**도구 이름:** `TaskOutput`. 이전 이름 `BashOutput`은 여전히 별칭으로 허용됩니다.3352Claude Code v2.1.277에서 제거됨. 이전에는 실행 중이거나 완료된 백그라운드 작업의 출력을 검색했으며, `BashOutput`은 별칭으로 허용되었습니다. Claude는 `Read`를 사용하여 백그라운드 작업의 출력 파일을 읽습니다.

3354 3353 

3355<Note>`TaskOutput`은 더 이상 사용되지 않습니다. 작업의 출력 파일 경로에서 `Read`를 사용하는 것을 선호하십시오. 아래 스키마는 도구를 만나는 훅 및 권한 처리기에 대해 유효합니다.</Note>3354`disallowed_tools` 항목 또는 두 이름 중 하나를 여전히 지정하는 거부 규칙은 경고 없이 무시됩니다.

3356 

3357**입력:**

3358 

3359```python theme={null}

3360{

3361 "task_id": str, # 출력을 가져올 작업 ID

3362 "block": bool, # 완료를 기다릴지 여부 (기본값 True)

3363 "timeout": int, # 최대 대기 시간(ms) (기본값 30000)

3364}

3365```

3366 

3367**출력:**

3368 

3369```python theme={null}

3370{

3371 "retrieval_status": "success" | "timeout" | "not_ready", # 출력이 검색되었는지 여부

3372 "task": dict | None, # 작업 세부 정보: task_id, task_type, status, description, output, 그리고 exitCode와 같은 타입별 필드

3373}

3374```

3375 3355 

3376<h3 id="taskstop">3356<h3 id="taskstop">

3377 TaskStop3357 TaskStop

3629```3609```

3630 3610 

3631| 속성 | 타입 | 기본값 | 설명 |3611| 속성 | 타입 | 기본값 | 설명 |

3632| :-------------------------- | :---------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3612| :-------------------------- | :---------------------------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3633| `enabled` | `bool` | `False` | 명령 실행을 위한 샌드박스 모드 활성화 |3613| `enabled` | `bool` | `False` | 명령 실행을 위한 샌드박스 모드 활성화 |

3634| `autoAllowBashIfSandboxed` | `bool` | `True` | 샌드박스가 활성화되면 bash 명령 자동 승인 |3614| `autoAllowBashIfSandboxed` | `bool` | `True` | 샌드박스가 활성화되면 bash 명령 자동 승인 |

3635| `excludedCommands` | `list[str]` | `[]` | 항상 샌드박스 제한을 우회하는 명령 (예: `["docker"]`). 이들은 모델 개입 없이 자동으로 샌드박스되지 않은 상태로 실행됩니다 |3615| `excludedCommands` | `list[str]` | `[]` | 샌드박스 제한을 우회하는 명령 (예: `["docker *"]`). 이들은 모델 개입 없이 자동으로 샌드박스되지 않은 상태로 실행됩니다. [`sandbox.excludedCommands`](/docs/ko/settings-reference#sandbox-excludedcommands)에서 항목이 적용되는 시기를 다룹니다 |

3636| `allowUnsandboxedCommands` | `bool` | `True` | 모델이 샌드박스 외부에서 명령 실행을 요청하도록 허용합니다. `True`일 때, 모델은 도구 입력에서 `dangerouslyDisableSandbox`를 설정할 수 있으며, 이는 [권한 시스템](#permissions-fallback-for-unsandboxed-commands)으로 폴백됩니다 |3616| `allowUnsandboxedCommands` | `bool` | `True` | 모델이 샌드박스 외부에서 명령 실행을 요청하도록 허용합니다. `True`일 때, 모델은 도구 입력에서 `dangerouslyDisableSandbox`를 설정할 수 있으며, 이는 [권한 시스템](#permissions-fallback-for-unsandboxed-commands)으로 폴백됩니다 |

3637| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `None` | 네트워크 특정 샌드박스 구성 |3617| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `None` | 네트워크 특정 샌드박스 구성 |

3638| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `None` | 무시할 샌드박스 위반을 구성합니다 |3618| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `None` | 무시할 샌드박스 위반을 구성합니다 |

3737 샌드박스되지 않은 명령을 위한 권한 폴백3717 샌드박스되지 않은 명령을 위한 권한 폴백

3738</h3>3718</h3>

3739 3719 

3740`allowUnsandboxedCommands`가 활성화되면, 모델은 도구 입력에서 `dangerouslyDisableSandbox: True`를 설정하여 샌드박스 외부에서 명령 실행을 요청할 수 있습니다. 이러한 요청은 기존 권한 시스템으로 폴백되므로, `can_use_tool` 핸들러가 호출되어 사용자 정의 인증 로직을 구현할 수 있습니다. `excludedCommands`에 나열된 명령은 대신 자동으로 샌드박스를 우회하며, 모델 개입이 없습니다. [`SandboxSettings`](#sandboxsettings)를 참조하십시오.3720`allowUnsandboxedCommands`가 활성화되면, 모델은 도구 입력에서 `dangerouslyDisableSandbox: True`를 설정하여 샌드박스 외부에서 명령 실행을 요청할 수 있습니다. 이러한 요청은 기존 권한 시스템으로 폴백되므로, `can_use_tool` 핸들러가 호출되어 사용자 정의 인증 로직을 구현할 수 있습니다.

3721 

3722`excludedCommands` 항목은 대신 모델 개입 없이 샌드박스를 우회합니다. [`sandbox.excludedCommands`](/docs/ko/settings-reference#sandbox-excludedcommands)에서 항목이 적용되는 시기를 다룹니다.

3741 3723 

3742다음 예제는 각 샌드박스되지 않은 요청을 로깅하고 사용자 정의 인증 로직이 허용하지 않으면 거부합니다:3724다음 예제는 각 샌드박스되지 않은 요청을 로깅하고 사용자 정의 인증 로직이 허용하지 않으면 거부합니다:

3743 3725 

645이러한 성장을 세 가지 방식으로 제한할 수 있습니다: 서브에이전트가 중첩되는 깊이, 한 번에 실행되는 개수, 그리고 전체 쿼리가 소비하는 금액입니다. [`env`](/docs/ko/agent-sdk/typescript#options) 옵션을 통해 환경 변수로 깊이 및 동시성 제한을 설정하고, 쿼리 옵션으로 지출 제한을 설정합니다:645이러한 성장을 세 가지 방식으로 제한할 수 있습니다: 서브에이전트가 중첩되는 깊이, 한 번에 실행되는 개수, 그리고 전체 쿼리가 소비하는 금액입니다. [`env`](/docs/ko/agent-sdk/typescript#options) 옵션을 통해 환경 변수로 깊이 및 동시성 제한을 설정하고, 쿼리 옵션으로 지출 제한을 설정합니다:

646 646 

647| 제한 | 설정 방법 | 기본값 | 제한에 도달했을 때 Claude Code의 동작 |647| 제한 | 설정 방법 | 기본값 | 제한에 도달했을 때 Claude Code의 동작 |

648| :-- | :----------------------------------------------------- | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |648| :-- | :----------------------------------------------------- | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

649| 깊이 | [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/ko/env-vars) | 메인 에이전트 아래 `3`개 계층의 서브에이전트. `1`은 서브에이전트가 자신의 서브에이전트를 생성하지 못하도록 중지합니다 | 하단 계층의 서브에이전트가 생성할 수 없도록 남겨두므로 위임된 작업을 직접 수행합니다. [중첩된 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 참조 |649| 깊이 | [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/ko/env-vars) | 메인 에이전트 아래 `3`개 계층의 서브에이전트. `1`은 서브에이전트가 자신의 서브에이전트를 생성하지 못하도록 중지합니다 | 하단 계층의 서브에이전트가 생성할 수 없도록 남겨두므로 위임된 작업을 직접 수행합니다. [중첩된 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents) 참조 |

650| 동시성 | [`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`](/docs/ko/env-vars) | `20`개의 서브에이전트가 동시에 실행되며, Agent 도구로 Claude가 생성하는 모든 서브에이전트를 계산합니다 | 실행 중인 개수가 제한 아래로 떨어질 때까지 `Concurrent subagent limit reached`를 반환하여 다른 서브에이전트 생성을 거부합니다. [ultracode](/docs/ko/model-config#adjust-effort-level)가 활성화된 세션은 거부되지 않습니다. [동시 서브에이전트 제한](/docs/ko/sub-agents#concurrent-subagent-limit) 참조 |650| 동시성 | [`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`](/docs/ko/env-vars) | `20`개의 서브에이전트가 동시에 실행되며, Agent 도구로 Claude가 생성하는 모든 서브에이전트를 계산합니다 | 실행 중인 개수가 제한 아래로 떨어질 때까지 `Concurrent subagent limit reached`를 반환하여 다른 서브에이전트 생성을 거부합니다. [ultracode](/docs/ko/model-config#adjust-effort-level)가 활성화된 세션은 거부되지 않습니다. [동시 서브에이전트 제한](/docs/ko/sub-agents#concurrent-subagent-limit) 참조 |

651| 지출 | TypeScript의 `maxBudgetUsd`, Python의 `max_budget_usd` | 제한 없음. `total_cost_usd`와 비교되므로 서브에이전트 요청이 계산됩니다 | 세 가지 방식으로 상한을 적용합니다: 더 이상의 서브에이전트 생성을 거부하여 `Budget limit reached`를 반환하고, 여전히 실행 중인 백그라운드 서브에이전트를 중지하며, `error_max_budget_usd` 결과 서브타입으로 쿼리를 종료합니다. [턴 및 예산](/docs/ko/agent-sdk/agent-loop#turns-and-budget) 참조 |651| 지출 | TypeScript의 `maxBudgetUsd`, Python의 `max_budget_usd` | 제한 없음. 호출 자체의 지출을 계산하며, 서브에이전트 요청이 포함됩니다 | 세 가지 방식으로 상한을 적용합니다: 더 이상의 서브에이전트 생성을 거부하여 `Budget limit reached`를 반환하고, 여전히 실행 중인 백그라운드 서브에이전트를 중지하며, `error_max_budget_usd` 결과 서브타입으로 쿼리를 종료합니다. 세션 전체에서 상한이 어떻게 작동하는지는 [턴 및 예산](/docs/ko/agent-sdk/agent-loop#turns-and-budget)을 참조하십시오 |

652 652 

653두 SDK는 `env` 옵션을 다르게 처리합니다: TypeScript SDK는 서브프로세스 환경을 이것으로 대체하므로 `PATH`와 같은 변수를 유지하기 위해 `process.env`를 이것으로 전개하고, Python SDK는 이것을 상속된 환경에 병합합니다. 이 예제는 중첩을 끄고, 한 번에 최대 5개의 서브에이전트를 허용하며, 예상 지출이 \$5에 도달하면 쿼리를 중지합니다:653두 SDK는 `env` 옵션을 다르게 처리합니다: TypeScript SDK는 서브프로세스 환경을 이것으로 대체하므로 `PATH`와 같은 변수를 유지하기 위해 `process.env`를 이것으로 전개하고, Python SDK는 이것을 상속된 환경에 병합합니다. 이 예제는 중첩을 끄고, 한 번에 최대 5개의 서브에이전트를 허용하며, 예상 지출이 \$5에 도달하면 쿼리를 중지합니다:

654 654 

745 Claude가 서브에이전트에 위임하지 않음745 Claude가 서브에이전트에 위임하지 않음

746</h3>746</h3>

747 747 

748Claude가 서브에이전트에 위임하는 대신 작업을 직접 완료하는 경우:748Claude가 서브에이전트에 위임하지 않고 작업을 직접 완료하는 경우:

749 749 

750* **명시적 프롬프팅 사용**: 프롬프트에서 서브에이전트를 이름으로 언급하세요(예: "code-reviewer 에이전트를 사용하여...").750* **명시적 프롬프팅 사용**: 프롬프트에서 서브에이전트를 이름으로 언급합니다. 예를 들어 "code-reviewer 에이전트를 사용하여 인증 모듈을 확인하세요"

751* **명확한 설명 작성**: Claude가 작업을 적절히 일치시킬 수 있도록 서브에이전트를 사용해야 할 때를 정확히 설명하세요.751* **명확한 설명 작성**: 서브에이전트를 언제 사용할지 정확히 설명하여 Claude가 작업을 적절히 매칭할 수 있도록 합니다

752 752 

753<h3 id="filesystem-based-agents-not-loading">753<h3 id="filesystem-based-agents-not-loading">

754 파일 시스템 기반 에이전트가 로드되지 않음754 파일시스템 기반 에이전트가 로드되지 않음

755</h3>755</h3>

756 756 

757Claude Code는 `~/.claude/agents/` 및 `.claude/agents/`를 감시하며 새로운 또는 편집된 에이전트 파일을 몇 초 내에 선택하며, 재시작이 필요하지 않습니다. 정의가 나타나지 않으면 다음 원인들을 확인하세요:757Claude Code는 `~/.claude/agents/` 및 `.claude/agents/`를 감시하며 새로운 또는 편집된 에이전트 파일을 몇 초 내에 선택합니다. 재시작이 필요하지 않습니다. 정의가 나타나지 않으면 다음 원인들을 확인하세요:

758 758 

759* **새로운 `agents` 디렉토리**: 감시자는 세션이 시작될 때 존재했던 디렉토리만 포함하므로, 새 디렉토리의 첫 번째 파일은 세션 재시작이 필요합니다. 이것이 가장 일반적인 원인입니다.759* **새로운 `agents` 디렉토리**: 감시자는 세션이 시작될 때 존재했던 디렉토리만 감시하므로 새 디렉토리의 첫 번째 파일은 세션 재시작이 필요합니다. 이것이 가장 일반적인 원인입니다.

760* **잘못된 frontmatter 또는 중복된 `name`**: 파일의 YAML을 확인하고, 기존 에이전트가 이미 해당 `name`을 사용하고 있는지 확인하세요.760* **잘못된 frontmatter 또는 중복된 `name`**: 파일의 YAML을 확인하고 기존 에이전트가 이미 해당 `name`을 사용하고 있는지 확인합니다.

761* **`--disable-slash-commands`**: 이 플래그로 시작된 세션은 이러한 디렉토리를 감시하지 않으며 새 파일을 로드하려면 항상 재시작이 필요합니다.761* **`--disable-slash-commands`**: 이 플래그로 시작된 세션은 이러한 디렉토리를 감시하지 않으며 새 파일을 로드하려면 항상 재시작이 필요합니다.

762* **동일한 이름의 프로그래밍 방식 에이전트**: `query()`에 전달된 `agents`는 동일한 이름의 파일 시스템 에이전트를 재정의합니다.762* **추가된 디렉토리 아래의 파일**: Claude Code는 `add_dirs` (Python) 또는 `additionalDirectories` (TypeScript) 옵션이나 CLI의 `--add-dir` 또는 `/add-dir`로 추가된 디렉토리에서 `.claude/agents/`를 로드하지만 감시하지 않으므로 해당 위치의 새로운 또는 편집된 파일은 세션 재시작이 필요합니다.

763* **동일한 이름의 프로그래매틱 에이전트**: `query()`에 전달된 `agents`는 동일한 이름의 파일시스템 에이전트를 재정의합니다.

763 764 

764파일 형식에 대해서는 [서브에이전트 파일 작성 방법](/docs/ko/sub-agents#write-subagent-files)을 참조하세요.765파일 형식에 대해서는 [서브에이전트 파일 작성 방법](/docs/ko/sub-agents#write-subagent-files)을 참조하세요.

765 766 

62 `query()`62 `query()`

63</h3>63</h3>

64 64 

65Claude Code와 상호작용하기 위한 주요 함수입니다. 메시지가 도착할 때 스트리밍하는 비동기 생성기를 만듭니다.65Claude Code와 상호작용하기 위한 주요 함수입니다. 메시지가 도착하는 대로 스트리밍하는 비동기 생성기를 생성합니다.

66 66 

67```typescript theme={null}67```typescript theme={null}

68function query({68function query({

78 매개변수78 매개변수

79</h4>79</h4>

80 80 

81| 매개변수 | 타입 | 설명 |81| 매개변수 | 유형 | 설명 |

82| :-------- | :--------------------------------------------------------------- | :-------------------------------------- |82| :-------- | :--------------------------------------------------------------- | :------------------------------------ |

83| `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | 문자열 또는 스트리밍 모드용 비동기 반복 가능 객체로서의 입력 프롬프트 |83| `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | 문자열 또는 스트리밍 모드용 비동기 반복 가능 객체로 입력 프롬프트 |

84| `options` | [`Options`](#options) | 선택적 구성 객체 (아래 Options 타입 참조) |84| `options` | [`Options`](#options) | 선택적 구성 객체 (아래 Options 유형 참조) |

85 85 

86<h4 id="returns">86<h4 id="returns">

87 반환값87 반환값

88</h4>88</h4>

89 89 

90[`Query`](#query-object) 객체를 반환하며, 이는 추가 메서드를 포함하는 `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>`를 확장합니다.90추가 메서드가 포함된 `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>`를 확장하는 [`Query`](#query-object) 객체를 반환합니다.

91 91 

92<h3 id="startup">92<h3 id="startup">

93 `startup()`93 `startup()`

94</h3>94</h3>

95 95 

96프롬프트를 사용할 수 있기 전에 CLI 서브프로세스를 생성하고 초기화 핸드셰이크를 완료하여 미리 준비합니다. 반환된 [`WarmQuery`](#warmquery) 핸들은 나중에 프롬프트를 수락하고 이미 준비된 프로세스에 작성하므로, 첫 번째 `query()` 호출은 서브프로세스 생성 및 초기화 비용을 지불하지 않고 해결됩니다.96프롬프트를 사용할 수 있기 전에 CLI 부프로세스를 생성하고 초기화 핸드셰이크를 완료하여 미리 준비합니다. 반환된 [`WarmQuery`](#warmquery) 핸들은 나중에 프롬프트를 수락하고 이미 준비된 프로세스에 작성하므로 첫 번째 `query()` 호출이 부프로세스 생성 및 초기화 비용을 인라인으로 지불하지 않고 해결됩니다.

97 97 

98```typescript theme={null}98```typescript theme={null}

99function startup(params?: {99function startup(params?: {

106 매개변수106 매개변수

107</h4>107</h4>

108 108 

109| 매개변수 | 타입 | 설명 |109| 매개변수 | 유형 | 설명 |

110| :-------------------- | :-------------------- | :--------------------------------------------------------------------------------------- |110| :-------------------- | :-------------------- | :-------------------------------------------------------------------------------------- |

111| `options` | [`Options`](#options) | 선택적 구성 객체입니다. `query()`의 `options` 매개변수와 동일합니다 |111| `options` | [`Options`](#options) | 선택적 구성 객체입니다. `query()`의 `options` 매개변수와 동일합니다 |

112| `initializeTimeoutMs` | `number` | 서브프로세스 초기화를 기다릴 최대 시간(밀리초)입니다. 기본값은 `60000`입니다. 초기화가 시간 내에 완료되지 않으면 프로미스는 타임아웃 오류로 거부됩니다 |112| `initializeTimeoutMs` | `number` | 부프로세스 초기화를 기다릴 최대 시간(밀리초)입니다. 기본값은 `60000`입니다. 초기화가 시간 내에 완료되지 않으면 프로미스가 타임아웃 오류로 거부됩니다 |

113 113 

114<h4 id="returns-2">114<h4 id="returns-2">

115 반환값115 반환값

116</h4>116</h4>

117 117 

118서브프로세스가 생성되고 초기화 핸드셰이크를 완료하면 해결되는 `Promise<`[`WarmQuery`](#warmquery)`>`를 반환합니다.118부프로세스가 생성되고 초기화 핸드셰이크를 완료한 후 해결되는 `Promise<`[`WarmQuery`](#warmquery)`>`를 반환합니다.

119 119 

120<h4 id="example">120<h4 id="example">

121 예제121 예제

122</h4>122</h4>

123 123 

124`startup()`을 조기에 호출합니다(예: 애플리케이션 부팅 시). 그런 다음 프롬프트가 준비되면 반환된 핸들에서 `.query()`를 호출합니다. 이렇게 하면 서브프로세스 생성 및 초기화가 중요 경로에서 벗어납니다.124`startup()`을 조기에 호출합니다(예: 애플리케이션 부팅 시). 그런 다음 프롬프트가 준비되면 반환된 핸들에서 `.query()`를 호출합니다. 이렇게 하면 부프로세스 생성 및 초기화가 중요 경로에서 제거됩니다.

125 125 

126```typescript theme={null}126```typescript theme={null}

127import { startup } from "@anthropic-ai/claude-agent-sdk";127import { startup } from "@anthropic-ai/claude-agent-sdk";

129// 시작 비용을 미리 지불합니다129// 시작 비용을 미리 지불합니다

130const warm = await startup({ options: { maxTurns: 3 } });130const warm = await startup({ options: { maxTurns: 3 } });

131 131 

132// 나중에 프롬프트가 준비되면 이것은 즉시입니다132// 나중에 프롬프트가 준비되면 즉시 실행됩니다

133for await (const message of warm.query("What files are here?")) {133for await (const message of warm.query("What files are here?")) {

134 console.log(message);134 console.log(message);

135}135}

139 `tool()`139 `tool()`

140</h3>140</h3>

141 141 

142SDK MCP 서버와 함께 사용하기 위한 타입 안전 MCP 도구 정의를 만듭니다.142SDK MCP 서버와 함께 사용할 유형 안전 MCP 도구 정의를 생성합니다.

143 143 

144```typescript theme={null}144```typescript theme={null}

145function tool<Schema extends AnyZodRawShape>(145function tool<Schema extends AnyZodRawShape>(

155 매개변수155 매개변수

156</h4>156</h4>

157 157 

158| 매개변수 | 타입 | 설명 |158| 매개변수 | 유형 | 설명 |

159| :------------ | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |159| :------------ | :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

160| `name` | `string` | 도구의 이름 |160| `name` | `string` | 도구의 이름 |

161| `description` | `string` | 도구가 수행하는 작업에 대한 설명 |161| `description` | `string` | 도구가 수행하는 작업에 대한 설명 |

162| `inputSchema` | `Schema extends AnyZodRawShape` | 도구의 입력 매개변수를 정의하는 Zod 스키마 (Zod 3 및 Zod 4 모두 지원) |162| `inputSchema` | `Schema extends AnyZodRawShape` | 도구의 입력 매개변수를 정의하는 Zod 스키마 (Zod 3 및 Zod 4 모두 지원) |

163| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | 도구 로직을 실행하는 비동기 함수 |163| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | 도구 로직을 실행하는 비동기 함수 |

164| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | 선택적 extras입니다. `annotations`은 클라이언트에 MCP 동작 힌트를 제공합니다. `searchHint`는 [도구 검색](/docs/ko/agent-sdk/tool-search)이 활성화되어 있을 때 지연된 도구 목록에 표시되는 한 줄의 기능 구문입니다. `alwaysLoad: true`는 이 도구의 전체 스키마를 초기 프롬프트에 유지하고 지연하지 않습니다 |164| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | 선택적 추가 항목입니다. `annotations`는 클라이언트에 MCP 동작 힌트를 제공합니다. `searchHint`는 [도구 검색](/docs/ko/agent-sdk/tool-search)이 활성화되어 있을 때 지연된 도구 목록에 표시되는 한 줄의 기능 구문입니다. `alwaysLoad: true`는 이 도구의 전체 스키마를 초기 프롬프트에 유지하고 지연하지 않습니다 |

165 165 

166<h4 id="toolannotations">166<h4 id="toolannotations">

167 `ToolAnnotations`167 `ToolAnnotations`

168</h4>168</h4>

169 169 

170`@modelcontextprotocol/sdk/types.js`에서 다시 내보냅니다. 모든 필드는 선택적 힌트입니다. 클라이언트는 보안 결정을 위해 이들을 신뢰해서는 안 됩니다.170`@modelcontextprotocol/sdk/types.js`에서 다시 내보냅니다. 모든 필드는 선택적 힌트이며 클라이언트는 보안 결정을 위해 이를 신뢰해서는 안 됩니다.

171 171 

172| 필드 | 타입 | 기본값 | 설명 |172| 필드 | 유형 | 기본값 | 설명 |

173| :---------------- | :-------- | :---------- | :---------------------------------------------------------------------------- |173| :---------------- | :-------- | :---------- | :-------------------------------------------------------------------------------- |

174| `title` | `string` | `undefined` | 도구의 사람이 읽을 수 있는 제목 |174| `title` | `string` | `undefined` | 도구의 사람이 읽을 수 있는 제목 |

175| `readOnlyHint` | `boolean` | `false` | `true`이면 도구는 환경을 수정하지 않습니다 |175| `readOnlyHint` | `boolean` | `false` | `true`인 경우 도구는 환경을 수정하지 않습니다 |

176| `destructiveHint` | `boolean` | `true` | `true`이면 도구는 파괴적인 업데이트를 수행할 수 있습니다 (`readOnlyHint`가 `false`일 때만 의미 있음) |176| `destructiveHint` | `boolean` | `true` | `true`인 경우 도구는 파괴적인 업데이트를 수행할 수 있습니다 (`readOnlyHint`가 `false`일 때만 의미 있음) |

177| `idempotentHint` | `boolean` | `false` | `true`이면 동일한 인수로 반복 호출해도 추가 효과가 없습니다 (`readOnlyHint`가 `false`일 때만 의미 있음) |177| `idempotentHint` | `boolean` | `false` | `true`인 경우 동일한 인수로 반복 호출해도 추가 효과가 없습니다 (`readOnlyHint`가 `false`일 때만 의미 있음) |

178| `openWorldHint` | `boolean` | `true` | `true`이면 도구는 외부 엔티티와 상호작용합니다 (예: 웹 검색). `false`이면 도구의 도메인은 폐쇄적입니다 (예: 메모리 도구) |178| `openWorldHint` | `boolean` | `true` | `true`인 경우 도구는 외부 엔티티와 상호작용합니다 (예: 웹 검색). `false`인 경우 도구의 도메인은 폐쇄적입니다 (예: 메모리 도구) |

179 179 

180```typescript theme={null}180```typescript theme={null}

181import { tool } from "@anthropic-ai/claude-agent-sdk";181import { tool } from "@anthropic-ai/claude-agent-sdk";

196 `createSdkMcpServer()`196 `createSdkMcpServer()`

197</h3>197</h3>

198 198 

199애플리케이션과 동일한 프로세스에서 실행되는 MCP 서버 인스턴스를 만듭니다.199애플리케이션과 동일한 프로세스에서 실행되는 MCP 서버 인스턴스를 생성합니다.

200 200 

201```typescript theme={null}201```typescript theme={null}

202function createSdkMcpServer(options: {202function createSdkMcpServer(options: {

213 매개변수213 매개변수

214</h4>214</h4>

215 215 

216| 매개변수 | 타입 | 설명 |216| 매개변수 | 유형 | 설명 |

217| :--------------------- | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |217| :--------------------- | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

218| `options.name` | `string` | MCP 서버의 이름 |218| `options.name` | `string` | MCP 서버의 이름 |

219| `options.version` | `string` | 선택적 버전 문자열 |219| `options.version` | `string` | 선택적 버전 문자열 |

220| `options.instructions` | `string` | 선택적 서버 지침이며, `initialize`에서 반환되고 MCP 지침 블록으로 모델에 표시됩니다 |220| `options.instructions` | `string` | 선택적 서버 지침이며, `initialize`에서 반환되고 MCP 지침 블록으로 모델에 표시됩니다 |

221| `options.tools` | `Array<SdkMcpToolDefinition>` | [`tool()`](#tool)로 만든 도구 정의의 배열 |221| `options.tools` | `Array<SdkMcpToolDefinition>` | [`tool()`](#tool)로 생성된 도구 정의 배열 |

222| `options.alwaysLoad` | `boolean` | `true`일 때 이 서버의 모든 도구는 초기 프롬프트에 유지되고 [도구 검색](/docs/ko/agent-sdk/tool-search) 뒤에서 지연되지 않습니다. [`tool()`](#tool)의 도구별 `alwaysLoad`와 결합됩니다 |222| `options.alwaysLoad` | `boolean` | `true`인 경우 이 서버의 모든 도구는 초기 프롬프트에 유지되며 [도구 검색](/docs/ko/agent-sdk/tool-search) 뒤에서 지연되지 않습니다. [`tool()`](#tool)의 도구별 `alwaysLoad`와 결합됩니다 |

223| `options.timeout` | `number` | 이 서버의 도구 호출에 대한 타임아웃(밀리초)입니다. Claude Code는 [`MCP_TOOL_TIMEOUT`](/docs/ko/env-vars)을 대신하여 이 서버에 적용합니다. 최소 1000의 정수를 전달합니다. Claude Code는 다른 값을 무시합니다. TypeScript Agent SDK v0.3.248 이상 필요 |223| `options.timeout` | `number` | 이 서버의 도구 호출에 대한 타임아웃(밀리초)입니다. Claude Code는 [`MCP_TOOL_TIMEOUT`](/docs/ko/env-vars)을 대신하여 이 서버에 적용합니다. 최소 1000의 정수를 전달합니다. Claude Code는 다른 값을 무시합니다. TypeScript Agent SDK v0.3.248 이상이 필요합니다 |

224 224 

225<h3 id="listsessions">225<h3 id="listsessions">

226 `listSessions()`226 `listSessions()`

236 매개변수236 매개변수

237</h4>237</h4>

238 238 

239| 매개변수 | 타입 | 기본값 | 설명 |239| 매개변수 | 유형 | 기본값 | 설명 |

240| :------------------------- | :-------- | :---------- | :------------------------------------------------ |240| :------------------------- | :-------- | :---------- | :------------------------------------------------ |

241| `options.dir` | `string` | `undefined` | 세션을 나열할 디렉토리입니다. 생략하면 모든 프로젝트에서 세션을 반환합니다 |241| `options.dir` | `string` | `undefined` | 세션을 나열할 디렉토리입니다. 생략하면 모든 프로젝트에서 세션을 반환합니다 |

242| `options.limit` | `number` | `undefined` | 반환할 최대 세션 수 |242| `options.limit` | `number` | `undefined` | 반환할 최대 세션 수 |

243| `options.includeWorktrees` | `boolean` | `true` | `dir`이 git 저장소 내에 있을 때 모든 worktree 경로에서 세션을 포함합니다 |243| `options.includeWorktrees` | `boolean` | `true` | `dir`이 git 저장소 내에 있을 때 모든 worktree 경로에서 세션을 포함합니다 |

244 244 

245<h4 id="return-type-sdksessioninfo">245<h4 id="return-type-sdksessioninfo">

246 반환 타입: `SDKSessionInfo`246 반환 유형: `SDKSessionInfo`

247</h4>247</h4>

248 248 

249| 속성 | 타입 | 설명 |249| 속성 | 유형 | 설명 |

250| :------------- | :-------------------- | :------------------------------------------------ |250| :------------- | :-------------------- | :---------------------------------------------- |

251| `sessionId` | `string` | 고유 세션 식별자 (UUID) |251| `sessionId` | `string` | 고유 세션 식별자 (UUID) |

252| `summary` | `string` | 표시 제목: 사용자 정의 제목, 자동 생성된 요약 또는 첫 번째 프롬프트 |252| `summary` | `string` | 표시 제목: 사용자 정의 제목, 자동 생성된 요약 또는 첫 번째 프롬프트 |

253| `lastModified` | `number` | 에포크 이후 밀리초 단위의 마지막 수정 시간 |253| `lastModified` | `number` | 마지막 수정 시간(에포크 이후 밀리초) |

254| `fileSize` | `number \| undefined` | 세션 파일 크기(바이트)입니다. 로컬 JSONL 저장소에만 채워집니다 |254| `fileSize` | `number \| undefined` | 세션 파일 크기(바이트)입니다. 로컬 JSONL 저장소에만 채워집니다 |

255| `customTitle` | `string \| undefined` | 사용자가 설정한 세션 제목 (`/rename`을 통해) |255| `customTitle` | `string \| undefined` | 사용자 설정 세션 제목 (`/rename`을 통해) |

256| `firstPrompt` | `string \| undefined` | 세션의 첫 번째 의미 있는 사용자 프롬프트 |256| `firstPrompt` | `string \| undefined` | 세션의 첫 번째 의미 있는 사용자 프롬프트 |

257| `gitBranch` | `string \| undefined` | 세션 끝의 git 분기 |257| `gitBranch` | `string \| undefined` | 세션 끝의 Git 분기 |

258| `cwd` | `string \| undefined` | 세션의 작업 디렉토리 |258| `cwd` | `string \| undefined` | 세션의 작업 디렉토리 |

259| `tag` | `string \| undefined` | 사용자가 설정한 세션 태그 ([`tagSession()`](#tagsession) 참조) |259| `tag` | `string \| undefined` | 사용자 설정 세션 태그 ([`tagSession()`](#tagsession) 참조) |

260| `createdAt` | `number \| undefined` | 첫 번째 항목의 타임스탬프에서 에포크 이후 밀리초 단위의 생성 시간 |260| `createdAt` | `number \| undefined` | 생성 시간(에포크 이후 밀리초)이며, 첫 번째 항목의 타임스탬프에서 가져옵니다 |

261 261 

262<h4 id="example-2">262<h4 id="example-2">

263 예제263 예제

264</h4>264</h4>

265 265 

266프로젝트의 10개 최신 세션을 인쇄합니다. 결과는 `lastModified` 내림차순으로 정렬되므로 첫 번째 항목이 가장 최신입니다. 모든 프로젝트에서 검색하려면 `dir`을 생략합니다.266프로젝트의 10개 최신 세션을 인쇄합니다. 결과는 `lastModified` 내림차순으로 정렬되므로 첫 번째 항목이 가장 최신입니다. `dir`을 생략하여 모든 프로젝트에서 검색합니다.

267 267 

268```typescript theme={null}268```typescript theme={null}

269import { listSessions } from "@anthropic-ai/claude-agent-sdk";269import { listSessions } from "@anthropic-ai/claude-agent-sdk";

279 `getSessionMessages()`279 `getSessionMessages()`

280</h3>280</h3>

281 281 

282과거 세션 트랜스크립트에서 사용자 및 어시스턴트 메시지를 읽습니다.282과거 세션 기록에서 사용자 및 어시스턴트 메시지를 읽습니다.

283 283 

284```typescript theme={null}284```typescript theme={null}

285function getSessionMessages(285function getSessionMessages(

292 매개변수292 매개변수

293</h4>293</h4>

294 294 

295| 매개변수 | 타입 | 기본값 | 설명 |295| 매개변수 | 유형 | 기본값 | 설명 |

296| :--------------- | :------- | :---------- | :------------------------------------------------ |296| :--------------- | :------- | :---------- | :--------------------------------------- |

297| `sessionId` | `string` | 필수 | 읽을 세션 UUID ([`listSessions()`](#listsessions) 참조) |297| `sessionId` | `string` | 필수 | 읽을 세션 UUID (`listSessions()` 참조) |

298| `options.dir` | `string` | `undefined` | 세션을 찾을 프로젝트 디렉토리입니다. 생략하면 모든 프로젝트를 검색합니다 |298| `options.dir` | `string` | `undefined` | 세션을 찾을 프로젝트 디렉토리입니다. 생략하면 모든 프로젝트를 검색합니다 |

299| `options.limit` | `number` | `undefined` | 반환할 최대 메시지 수 |299| `options.limit` | `number` | `undefined` | 반환할 최대 메시지 수 |

300| `options.offset` | `number` | `undefined` | 시작 부분에서 건너뛸 메시지 수 |300| `options.offset` | `number` | `undefined` | 시작 부분에서 건너뛸 메시지 수 |

301 301 

302<h4 id="return-type-sessionmessage">302<h4 id="return-type-sessionmessage">

303 반환 타입: `SessionMessage`303 반환 유형: `SessionMessage`

304</h4>304</h4>

305 305 

306| 속성 | 타입 | 설명 |306| 속성 | 유형 | 설명 |

307| :------------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |307| :------------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

308| `type` | `"user" \| "assistant"` | 메시지 역할 |308| `type` | `"user" \| "assistant"` | 메시지 역할 |

309| `uuid` | `string` | 고유 메시지 식별자 |309| `uuid` | `string` | 고유 메시지 식별자 |

310| `session_id` | `string` | 이 메시지가 속한 세션 |310| `session_id` | `string` | 이 메시지가 속한 세션 |

311| `message` | `unknown` | 트랜스크립트의 원본 메시지 페이로드 |311| `message` | `unknown` | 기록에서 원본 메시지 페이로드 |

312| `parent_tool_use_id` | `string \| null` | 서브에이전트 메시지의 경우 생성 `Agent` 도구 호출의 `tool_use_id`입니다. 메인 세션 메시지 및 이전 세션의 경우 `null` |312| `parent_tool_use_id` | `string \| null` | 부에이전트 메시지의 경우 부에이전트를 시작한 `Agent` 또는 `Skill` 도구 호출의 `tool_use_id`입니다. 주 세션 메시지 및 이전 세션의 경우 `null` |

313| `parent_agent_id` | `string \| null` | [중첩된 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)의 메시지의 경우 이를 생성한 서브에이전트의 `agentId`입니다. 메인 세션 메시지, 최상위 서브에이전트의 메시지 및 이전 세션의 경우 `null`입니다. Claude Code v2.1.202 이상 필요 |313| `parent_agent_id` | `string \| null` | [중첩된 부에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)의 메시지의 경우 이를 생성한 부에이전트의 `agentId`입니다. 주 세션 메시지, 최상위 부에이전트의 메시지 및 이전 세션의 경우 `null`입니다. Claude Code v2.1.202 이상이 필요합니다 |

314 314 

315<h4 id="example-3">315<h4 id="example-3">

316 예제316 예제

337 `getSessionInfo()`337 `getSessionInfo()`

338</h3>338</h3>

339 339 

340전체 프로젝트 디렉토리를 스캔하지 않고 ID로 단일 세션의 메타데이터를 읽습니다.340전체 프로젝트 디렉토리를 스캔하지 않고 ID별로 단일 세션의 메타데이터를 읽습니다.

341 341 

342```typescript theme={null}342```typescript theme={null}

343function getSessionInfo(343function getSessionInfo(

350 매개변수350 매개변수

351</h4>351</h4>

352 352 

353| 매개변수 | 타입 | 기본값 | 설명 |353| 매개변수 | 유형 | 기본값 | 설명 |

354| :------------ | :------- | :---------- | :---------------------------------------- |354| :------------ | :------- | :---------- | :---------------------------------------- |

355| `sessionId` | `string` | 필수 | 조회할 세션의 UUID |355| `sessionId` | `string` | 필수 | 조회할 세션의 UUID |

356| `options.dir` | `string` | `undefined` | 프로젝트 디렉토리 경로입니다. 생략하면 모든 프로젝트 디렉토리를 검색합니다 |356| `options.dir` | `string` | `undefined` | 프로젝트 디렉토리 경로입니다. 생략하면 모든 프로젝트 디렉토리를 검색합니다 |

361 `renameSession()`361 `renameSession()`

362</h3>362</h3>

363 363 

364사용자 정의 제목 항목을 추가하여 세션의 이름을 바꿉니다. 반복 호출은 안전합니다. 가장 최신 제목이 우선합니다.364사용자 정의 제목 항목을 추가하여 세션의 이름을 바꿉니다. 반복 호출은 안전하며 가장 최근 제목이 우선합니다.

365 365 

366```typescript theme={null}366```typescript theme={null}

367function renameSession(367function renameSession(

375 매개변수375 매개변수

376</h4>376</h4>

377 377 

378| 매개변수 | 타입 | 기본값 | 설명 |378| 매개변수 | 유형 | 기본값 | 설명 |

379| :------------ | :------- | :---------- | :---------------------------------------- |379| :------------ | :------- | :---------- | :---------------------------------------- |

380| `sessionId` | `string` | 필수 | 이름을 바꿀 세션의 UUID |380| `sessionId` | `string` | 필수 | 이름을 바꿀 세션의 UUID |

381| `title` | `string` | 필수 | 새 제목입니다. 공백을 제거한 후 비어 있지 않아야 합니다 |381| `title` | `string` | 필수 | 새 제목입니다. 공백을 제거한 후 비어 있지 않아야 합니다 |

385 `tagSession()`385 `tagSession()`

386</h3>386</h3>

387 387 

388세션에 태그를 지정합니다. `null`을 전달하여 태그를 지웁니다. 반복 호출은 안전합니다. 가장 최신 태그가 우선합니다.388세션에 태그를 지정합니다. 태그를 지우려면 `null`을 전달합니다. 반복 호출은 안전하며 가장 최근 태그가 우선합니다.

389 389 

390```typescript theme={null}390```typescript theme={null}

391function tagSession(391function tagSession(

399 매개변수399 매개변수

400</h4>400</h4>

401 401 

402| 매개변수 | 타입 | 기본값 | 설명 |402| 매개변수 | 유형 | 기본값 | 설명 |

403| :------------ | :--------------- | :---------- | :---------------------------------------- |403| :------------ | :--------------- | :---------- | :---------------------------------------- |

404| `sessionId` | `string` | 필수 | 태그를 지정할 세션의 UUID |404| `sessionId` | `string` | 필수 | 태그를 지정할 세션의 UUID |

405| `tag` | `string \| null` | 필수 | 태그 문자열 또는 지우려면 `null` |405| `tag` | `string \| null` | 필수 | 태그 문자열 또는 지우려면 `null` |

409 `resolveSettings()`409 `resolveSettings()`

410</h3>410</h3>

411 411 

412CLI와 동일한 병합 엔진을 사용하여 주어진 디렉토리에 대한 효과적인 Claude Code 설정을 해결하며, Claude CLI를 생성하지 않습니다. `query()` 호출을 호출하기 전에 어떤 구성을 볼 수 있는지 검사하는 데 사용합니다.412CLI를 생성하지 않고 CLI와 동일한 병합 엔진을 사용하여 주어진 디렉토리에 대한 효과적인 Claude Code 설정을 해결합니다. `query()` 호출을 호출하기 전에 `query()` 호출이 볼 구성을 검사하는 데 사용합니다.

413 413 

414<Note>414<Note>

415 이 함수는 알파 버전이며 안정화 전에 API가 변경될 수 있습니다.415 이 함수는 알파 버전이며 안정화 전에 API가 변경될 수 있습니다.

417 417 

418스냅샷은 라이브 `query()` 세션이 적용하는 것과 다릅니다:418스냅샷은 라이브 `query()` 세션이 적용하는 것과 다릅니다:

419 419 

420* **`policyHelper`**: `resolveSettings()`는 macOS plist 및 Windows HKLM/HKCU를 포함한 MDM 소스를 읽지만, 관리자가 구성한 `policyHelper` 서브프로세스를 실행하지 않습니다.420* **`policyHelper`**: `resolveSettings()`는 macOS plist 및 Windows HKLM/HKCU를 포함한 MDM 소스를 읽지만 관리자 구성 `policyHelper` 부프로세스를 실행하지 않습니다.

421* **서버 관리 설정**: `resolveSettings()`는 [서버 관리 설정](/docs/ko/server-managed-settings#fetch-and-caching-behavior)을 가져오지 않습니다. 이를 포함하려면 `options.serverManagedSettings`로 전달합니다.421* **서버 관리 설정**: `resolveSettings()`는 [서버 관리 설정](/docs/ko/server-managed-settings#fetch-and-caching-behavior)을 가져오지 않습니다. 포함하려면 `options.serverManagedSettings`으로 전달합니다.

422* **`defaultMode`**: 스냅샷은 모든 계층에서 `permissions.defaultMode`를 그대로 반환하므로, [라이브 세션이 무시하는](/docs/ko/permission-modes#which-mode-a-session-starts-in) 프로젝트 및 로컬 설정의 `'auto'` 및 `'bypassPermissions'` 값을 포함할 수 있습니다.422* **`defaultMode`**: 스냅샷은 모든 계층에서 `permissions.defaultMode`를 그대로 반환하므로 프로젝트 및 로컬 설정의 `'auto'` 및 `'bypassPermissions'` 값을 포함할 수 있으며, [라이브 세션은 무시합니다](/docs/ko/permission-modes#which-mode-a-session-starts-in).

423 423 

424```typescript theme={null}424```typescript theme={null}

425function resolveSettings(425function resolveSettings(

433 433 

434`resolveSettings()`는 단일 옵션 객체를 수락합니다. 모든 필드는 선택적입니다.434`resolveSettings()`는 단일 옵션 객체를 수락합니다. 모든 필드는 선택적입니다.

435 435 

436| 매개변수 | 타입 | 기본값 | 설명 |436| 매개변수 | 유형 | 기본값 | 설명 |

437| :------------------------------ | :------------------------------------ | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |437| :------------------------------ | :------------------------------------ | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

438| `options.cwd` | `string` | `process.cwd()` | 프로젝트 및 로컬 설정을 상대적으로 해결할 디렉토리 |438| `options.cwd` | `string` | `process.cwd()` | 프로젝트 및 로컬 설정을 상대적으로 해결할 디렉토리 |

439| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 모든 소스 | 로드할 파일 시스템 소스입니다. 사용자, 프로젝트 및 로컬 설정을 건너뛰려면 `[]`를 전달합니다. 엔드포인트 관리 정책은 모든 경우에 로드됩니다. `resolveSettings()`는 `options.serverManagedSettings`를 전달할 때만 서버 관리 설정을 포함합니다 |439| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 모든 소스 | 로드할 파일 시스템 소스입니다. 사용자, 프로젝트 및 로컬 설정을 건너뛰려면 `[]`을 전달합니다. [엔드포인트 관리 정책](/docs/ko/managed-settings#delivery-mechanisms)은 모든 경우에 로드됩니다. `resolveSettings()`는 `options.serverManagedSettings`을 전달할 때만 서버 관리 설정을 포함합니다 |

440| `options.managedSettings` | `Settings` | `undefined` | 임베딩 호스트가 제공하는 정책 계층 설정입니다. [`Options`](#options)의 [`managedSettings`](#options)와 동일한 규칙을 따릅니다. 단, `resolveSettings()`는 구성된 [`policyHelper`](/docs/ko/settings-reference#policyhelper)를 실행하지 않으므로, 스냅샷은 라이브 세션이 삭제하는 설정을 포함할 수 있습니다 |440| `options.managedSettings` | `Settings` | `undefined` | 임베딩 호스트에서 제공하는 정책 계층 설정입니다. [`managedSettings` in `Options`](#options)와 동일한 규칙을 따릅니다. 단, `resolveSettings()`는 구성된 [`policyHelper`](/docs/ko/settings-reference#policyhelper)를 실행하지 않으므로 스냅샷은 라이브 세션이 삭제하는 설정을 포함할 수 있습니다 |

441| `options.serverManagedSettings` | `Settings` | `undefined` | `/api/claude_code/settings`의 서버 관리 설정 페이로드입니다. 제한적이지 않은 키는 필터링 없이 통과합니다 |441| `options.serverManagedSettings` | `Settings` | `undefined` | `/api/claude_code/settings`의 서버 관리 설정 페이로드입니다. 제한이 없는 키는 필터링되지 않고 통과합니다 |

442 442 

443<h4 id="return-type-resolvedsettings">443<h4 id="return-type-resolvedsettings">

444 반환 타입: `ResolvedSettings`444 반환 유형: `ResolvedSettings`

445</h4>445</h4>

446 446 

447`resolveSettings()`는 병합된 설정과 각 키에 기여한 소스를 설명하는 객체를 반환합니다.447`resolveSettings()`는 병합된 설정 및 각 키에 기여한 소스를 설명하는 객체를 반환합니다.

448 448 

449| 속성 | 타입 | 설명 |449| 속성 | 유형 | 설명 |

450| :----------- | :-------------------------------------------------- | :----------------------------------------- |450| :----------- | :-------------------------------------------------- | :--------------------------------------------- |

451| `effective` | `Settings` | 모든 활성화된 소스를 우선순위 순서로 적용한 후 병합된 설정 |451| `effective` | `Settings` | 모든 활성화된 소스를 우선순위 순서로 적용한 후 병합된 설정 |

452| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | `effective`의 각 최상위 키에 대해 값을 제공한 소스 |452| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | `effective`의 각 최상위 키에 대해 값을 제공한 소스 |

453| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 소스별 원본 설정, 가장 낮은 우선순위에서 가장 높은 우선순위 순서로 정렬됨 |453| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 소스별 원본 설정이며, 가장 낮은 우선순위에서 가장 높은 우선순위 순서로 정렬됩니다 |

454 454 

455<h4 id="example-4">455<h4 id="example-4">

456 예제456 예제

504| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수입니다 |504| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수입니다 |

505| `fallbackModel` | `string` | `undefined` | 기본 모델이 실패할 경우 사용할 모델입니다. 쉼표로 구분된 목록을 허용합니다. 순서 및 상한에 대해서는 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)을 참조하세요. 지침은 [모델 선택](/docs/ko/agent-sdk/configuration#choose-a-model)을 참조하세요 |505| `fallbackModel` | `string` | `undefined` | 기본 모델이 실패할 경우 사용할 모델입니다. 쉼표로 구분된 목록을 허용합니다. 순서 및 상한에 대해서는 [폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)을 참조하세요. 지침은 [모델 선택](/docs/ko/agent-sdk/configuration#choose-a-model)을 참조하세요 |

506| `forkSession` | `boolean` | `false` | `resume`으로 재개할 때 원본 세션을 계속하는 대신 새 세션 ID로 포크합니다 |506| `forkSession` | `boolean` | `false` | `resume`으로 재개할 때 원본 세션을 계속하는 대신 새 세션 ID로 포크합니다 |

507| `forwardSubagentText` | `boolean` | `false` | 서브에이전트 텍스트 및 사고 블록을 `parent_tool_use_id`가 설정된 어시스턴트 및 사용자 메시지로 전달하여 소비자가 중첩된 대화록을 렌더링할 수 있도록 합니다. 이 옵션이 없으면 Claude Code는 서브에이전트 `tool_use` 및 `tool_result` 블록을 내보내지만 텍스트나 사고는 내보내지 않습니다. 모든 중첩 깊이의 서브에이전트 메시지는 Claude Code v2.1.219 이상에서 전달됩니다. v2.1.219 이전에는 깊이 1의 서브에이전트 메시지만 나타났습니다 |507| `forwardSubagentText` | `boolean` | `false` | 서브에이전트 텍스트 및 사고 블록을 `parent_tool_use_id`가 설정된 어시스턴트 및 사용자 메시지로 전달하여 소비자가 중첩된 대화록을 렌더링할 수 있도록 합니다. 이 옵션이 없으면 Claude Code는 서브에이전트 `tool_use` 및 `tool_result` 블록을 내보내지만 텍스트나 사고는 내보내지 않습니다. 모든 중첩 깊이의 서브에이전트 메시지는 Claude Code v2.1.219 이상에서 전달됩니다. v2.1.219 이전에는 깊이 1의 서브에이전트 메시지만 나타났습니다. 포크된 스킬이 생성하는 서브에이전트의 메시지와 중첩된 포크된 스킬의 메시지는 v2.1.275 이상이 필요합니다 |

508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백입니다 |508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백입니다 |

509| `includeHookEvents` | `boolean` | `false` | 훅 라이프사이클 이벤트를 메시지 스트림에 [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) 및 [`SDKHookResponseMessage`](#sdkhookresponsemessage)로 포함합니다. `SessionStart` 및 `Setup` 훅의 라이프사이클 이벤트는 항상 포함되며 이 옵션이 필요하지 않습니다. `Notification`, `SessionEnd`, `PreCompact` 및 `PostCompact` 같은 일부 훅 이벤트는 이 옵션이 있어도 `SDKHookStartedMessage`를 생성하지 않습니다. 이러한 이벤트의 경우 Claude Code는 여전히 `SDKHookProgressMessage`를 내보내고, 1초 이상 실행되는 명령어 훅은 출력을 내보내며, [백그라운드에서 실행되는](/docs/ko/hooks#run-hooks-in-the-background) 훅이 완료될 때만 `SDKHookResponseMessage`를 내보냅니다 |509| `includeHookEvents` | `boolean` | `false` | 훅 라이프사이클 이벤트를 메시지 스트림에 [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) 및 [`SDKHookResponseMessage`](#sdkhookresponsemessage)로 포함합니다. `SessionStart` 및 `Setup` 훅의 라이프사이클 이벤트는 항상 포함되며 이 옵션이 필요하지 않습니다. `Notification`, `SessionEnd`, `PreCompact` 및 `PostCompact` 같은 일부 훅 이벤트는 이 옵션이 있어도 `SDKHookStartedMessage`를 생성하지 않습니다. 이러한 이벤트의 경우 Claude Code는 여전히 `SDKHookProgressMessage`를 내보내고, 1초 이상 실행되는 명령어 훅은 출력을 내보내며, [백그라운드에서 실행되는](/docs/ko/hooks#run-hooks-in-the-background) 훅이 완료될 때만 `SDKHookResponseMessage`를 내보냅니다 |

510| `includePartialMessages` | `boolean` | `false` | 부분 메시지 이벤트를 포함합니다 |510| `includePartialMessages` | `boolean` | `false` | 부분 메시지 이벤트를 포함합니다 |

511| `loadTimeoutMs` | `number` | `60000` | *알파.* 재개 구체화 중 각 `sessionStore.load()` 및 `sessionStore.listSubkeys()` 호출에 대한 밀리초 단위 시간 초과입니다. 어댑터가 이 창 내에서 정착하지 않으면 쿼리가 중단되는 대신 실패합니다. `sessionStore`가 설정되지 않으면 무시됩니다 |511| `loadTimeoutMs` | `number` | `60000` | *알파.* 재개 구체화 중 각 `sessionStore.load()` 및 `sessionStore.listSubkeys()` 호출에 대한 밀리초 단위 시간 초과입니다. 어댑터가 이 창 내에서 정착하지 않으면 쿼리가 중단되는 대신 실패합니다. `sessionStore`가 설정되지 않으면 무시됩니다 |

512| `managedSettings` | `Settings` | `undefined` | 호스트 프로세스가 생성된 세션에 제공하는 정책 계층 설정입니다. 관리자가 배포한 관리 설정이 있는 머신에서 Claude Code는 관리자의 최우선 관리 소스가 `parentSettingsBehavior: 'merge'`를 설정하지 않으면 이를 무시하고, [`policyHelper`](/docs/ko/settings-reference#policyhelper)가 관리 설정을 제공하는 동안 절대 병합하지 않습니다. 병합된 값은 제한적 필터를 통과합니다. [부모 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)은 필터가 허용하는 것과 `allowManaged*Only` 잠금을 다룹니다. [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정한 호스트는 이 페이로드에서 직접 읽은 세 가지 키를 가집니다. Claude Code v2.1.222 이상의 [모델 구성](/docs/ko/model-config#restrict-model-selection), 관리 소스가 v2.1.246 이상에서 설정하지 않을 때 [`modelPricing`](/docs/ko/settings-reference#modelpricing), v2.1.247 이상에서 `ENABLE_TOOL_SEARCH` env 항목입니다 |512| `managedSettings` | `Settings` | `undefined` | 호스트 프로세스가 생성된 세션에 제공하는 정책 계층 설정입니다. 관리자가 배포한 관리 설정이 있는 머신에서 Claude Code는 관리자의 최우선 관리 소스가 `parentSettingsBehavior: 'merge'`를 설정하지 않으면 이를 무시하고, [`policyHelper`](/docs/ko/settings-reference#policyhelper)가 관리 설정을 제공하는 동안 절대 병합하지 않습니다. 병합된 값은 제한적 필터를 통과합니다. [부모 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)은 필터가 허용하는 것과 `allowManaged*Only` 잠금을 다룹니다. [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정한 호스트는 이 페이로드에서 직접 읽은 세 가지 키를 가집니다. Claude Code v2.1.222 이상의 [모델 구성](/docs/ko/model-config#restrict-model-selection), 관리 소스가 v2.1.246 이상에서 설정하지 않을 때 [`modelPricing`](/docs/ko/settings-reference#modelpricing), v2.1.247 이상에서 `ENABLE_TOOL_SEARCH` env 항목입니다 |

513| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리를 중지합니다. `total_cost_usd`와 동일한 추정과 비교됩니다. 정확도 주의 사항 및 재설정 동작은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요 |513| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리를 중지합니다. 호출 자체의 지출만 계산합니다. 재개된 세션에서 복원된 합계는 계산되지 않습니다. 정확도 주의 사항 및 재설정 동작은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요 |

514| `maxThinkingTokens` | `number` | `undefined` | *더 이상 사용되지 않음:* 대신 `thinking`을 사용하세요. 사고 프로세스의 최대 토큰 |514| `maxThinkingTokens` | `number` | `undefined` | *더 이상 사용되지 않음:* 대신 `thinking`을 사용하세요. 사고 프로세스의 최대 토큰 |

515| `maxTurns` | `number` | `undefined` | 최대 에이전트 턴(도구 사용 왕복) |515| `maxTurns` | `number` | `undefined` | 최대 에이전트 턴(도구 사용 왕복) |

516| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 서버 구성입니다 |516| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 서버 구성입니다 |

525| `persistSession` | `boolean` | `true` | `false`일 때, 디스크에 대한 세션 지속성을 비활성화합니다. 세션을 나중에 재개할 수 없습니다 |525| `persistSession` | `boolean` | `true` | `false`일 때, 디스크에 대한 세션 지속성을 비활성화합니다. 세션을 나중에 재개할 수 없습니다 |

526| `planModeInstructions` | `string` | `undefined` | 플랜 모드의 사용자 정의 워크플로우 지침입니다. `permissionMode`가 `'plan'`일 때, 이 문자열은 기본 플랜 모드 워크플로우 본문을 대체합니다. CLI는 여전히 읽기 전용 적용 프리앰블과 ExitPlanMode 프로토콜 바닥글로 래핑합니다 |526| `planModeInstructions` | `string` | `undefined` | 플랜 모드의 사용자 정의 워크플로우 지침입니다. `permissionMode`가 `'plan'`일 때, 이 문자열은 기본 플랜 모드 워크플로우 본문을 대체합니다. CLI는 여전히 읽기 전용 적용 프리앰블과 ExitPlanMode 프로토콜 바닥글로 래핑합니다 |

527| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | 로컬 경로에서 사용자 정의 플러그인을 로드합니다. [플러그인](/docs/ko/agent-sdk/plugins)의 세부 정보를 참조하세요 |527| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | 로컬 경로에서 사용자 정의 플러그인을 로드합니다. [플러그인](/docs/ko/agent-sdk/plugins)의 세부 정보를 참조하세요 |

528| `projectConfigRoot` | `string` | `undefined` | `cwd`가 worktree인 신뢰할 수 있는 체크아웃의 절대 경로입니다. Claude Code는 프로젝트 설정, `.mcp.json` 및 프로젝트의 `.claude/` 명령어, 에이전트, 스킬, 워크플로우, 루틴 및 출력 스타일을 `cwd` 대신 이 디렉토리에서 읽고 `CLAUDE_PROJECT_DIR`을 설정합니다. `CLAUDE.md` 파일 및 `.claude/rules/`는 여전히 `cwd`에서 로드됩니다. `apiKeyHelper` 같은 훅, 도우미 스크립트 및 stdio MCP 서버는 이 디렉토리를 작업 디렉토리로 시작합니다. Claude Code v2.1.275 이상이 필요합니다 |

528| `promptSuggestions` | `boolean` | `false` | 프롬프트 제안을 활성화합니다. 턴 후 Claude Code는 예측된 다음 사용자 프롬프트를 전달하는 `prompt_suggestion` 메시지를 내보냅니다. Claude Code는 계정이 사용량 한계에 가깝거나 도달했을 때와 같은 일부 턴에 대해 제안을 생성하지 않습니다. [Claude Code가 제안을 건너뛸 때](/docs/ko/interactive-mode#when-claude-code-skips-suggestions)를 참조하세요 |529| `promptSuggestions` | `boolean` | `false` | 프롬프트 제안을 활성화합니다. 턴 후 Claude Code는 예측된 다음 사용자 프롬프트를 전달하는 `prompt_suggestion` 메시지를 내보냅니다. Claude Code는 계정이 사용량 한계에 가깝거나 도달했을 때와 같은 일부 턴에 대해 제안을 생성하지 않습니다. [Claude Code가 제안을 건너뛸 때](/docs/ko/interactive-mode#when-claude-code-skips-suggestions)를 참조하세요 |

529| `resume` | `string` | `undefined` | 재개할 세션 ID입니다 |530| `resume` | `string` | `undefined` | 재개할 세션 ID입니다 |

530| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt`과 함께: 자르기 재개가 버릴 의도가 있는 턴의 프롬프트 UUID입니다. Claude Code는 버려진 범위에 해당 턴에 귀속될 수 없는 것(예: 흡수된 대기 메시지 또는 작업 알림)이 포함되면 재개를 거부하고 거부 메시지에서 `--resume-drops-turn` 플래그를 명시합니다. 에이전트 SDK 및 인쇄 모드 재개만 쌍을 읽습니다. Claude Code v2.1.223 이상이 필요합니다 |531| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt`과 함께: 자르기 재개가 버릴 의도가 있는 턴의 프롬프트 UUID입니다. Claude Code는 버려진 범위에 해당 턴에 귀속될 수 없는 것(예: 흡수된 대기 메시지 또는 작업 알림)이 포함되면 재개를 거부하고 거부 메시지에서 `--resume-drops-turn` 플래그를 명시합니다. 에이전트 SDK 및 인쇄 모드 재개만 쌍을 읽습니다. Claude Code v2.1.223 이상이 필요합니다 |

600 : Settings[K] | null;601 : Settings[K] | null;

601 }): Promise<void>;602 }): Promise<void>;

602 updateSettings(603 updateSettings(

603 source: 'localSettings',604 source: 'localSettings' | 'userSettings',

604 settings: Record<string, unknown>,605 settings: Record<string, unknown>,

605 ): Promise<void>;606 ): Promise<void>;

606 initializationResult(): Promise<SDKControlInitializeResponse>;607 initializationResult(): Promise<SDKControlInitializeResponse>;

621 reconnectMcpServer(serverName: string): Promise<void>;622 reconnectMcpServer(serverName: string): Promise<void>;

622 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;623 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;

623 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;624 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;

625 readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;

624 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;626 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;

625 stopTask(taskId: string): Promise<void>;627 stopTask(taskId: string): Promise<void>;

626 close(): void;628 close(): void;

639| `setModel()` | 모델을 변경합니다(스트리밍 입력 모드에서만 사용 가능). `undefined` 또는 문자열 `"default"`를 전달하면 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다 |641| `setModel()` | 모델을 변경합니다(스트리밍 입력 모드에서만 사용 가능). `undefined` 또는 문자열 `"default"`를 전달하면 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다 |

640| `setMaxThinkingTokens()` | *더 이상 사용되지 않음:* 대신 `thinking` 옵션을 사용하세요. 최대 사고 토큰을 변경합니다. `null`을 전달하면 사고를 세션 기본값으로 재설정합니다. 중간 세션 재정의가 지워지고, 사고가 비활성화된 세션의 경우 사고는 꺼진 상태로 유지됩니다 |642| `setMaxThinkingTokens()` | *더 이상 사용되지 않음:* 대신 `thinking` 옵션을 사용하세요. 최대 사고 토큰을 변경합니다. `null`을 전달하면 사고를 세션 기본값으로 재설정합니다. 중간 세션 재정의가 지워지고, 사고가 비활성화된 세션의 경우 사고는 꺼진 상태로 유지됩니다 |

641| `applyFlagSettings(settings)` | 런타임에 설정을 세션의 플래그 설정 계층으로 병합합니다(스트리밍 입력 모드에서만 사용 가능). [`applyFlagSettings()`](#applyflagsettings)를 참조하세요 |643| `applyFlagSettings(settings)` | 런타임에 설정을 세션의 플래그 설정 계층으로 병합합니다(스트리밍 입력 모드에서만 사용 가능). [`applyFlagSettings()`](#applyflagsettings)를 참조하세요 |

642| `updateSettings(source, settings)` | 설정을 프로젝트의 로컬 설정 파일 `.claude/settings.local.json`으로 병합합니다. 다음 요청에서 적용됩니다. `source: 'localSettings'` 및 현재 `outputStyle`인 허용 목록 키 집합만 허용합니다. 문자열 값 삭제는 지원되지 않습니다. 원격 전송 및 [`settingSources`](#options)가 `local`을 제외하는 세션에서 거부됩니다. TypeScript SDK v0.3.257 이상이 필요하며, Claude Code v2.1.257을 번들합니다 |644| `updateSettings(source, settings)` | 프로젝트의 로컬 설정 파일 또는 사용자 설정 파일에 허용 목록 키를 작성하여 값이 나중 세션에 지속되도록 합니다. [`updateSettings()`](#updatesettings)를 참조하세요. TypeScript SDK v0.3.257 이상이 필요하며, Claude Code v2.1.257을 번들합니다 |

643| `initializationResult()` | 지원되는 명령어, 모델, 계정 정보 및 출력 스타일 구성을 포함한 전체 초기화 결과를 반환합니다 |645| `initializationResult()` | 지원되는 명령어, 모델, 계정 정보 및 출력 스타일 구성을 포함한 전체 초기화 결과를 반환합니다 |

644| `reinitialize()` | 실행 중인 CLI에 `initialize` 제어 요청을 다시 보내고 캐시된 첫 연결 결과 대신 새로운 결과를 반환합니다. 연결 해제 후 세션에 다시 연결하는 것과 같은 전송 간격 후 사용하여 대기 중인 권한 요청이 `canUseTool` 콜백에 다시 도달하도록 합니다. 응답이 손실된 요청이 다시 전달되므로 요청 ID당 콜백을 멱등성으로 만드세요. Claude Code v2.1.195 이상이 필요합니다 |646| `reinitialize()` | 실행 중인 CLI에 `initialize` 제어 요청을 다시 보내고 캐시된 첫 연결 결과 대신 새로운 결과를 반환합니다. 연결 해제 후 세션에 다시 연결하는 것과 같은 전송 간격 후 사용하여 대기 중인 권한 요청이 `canUseTool` 콜백에 다시 도달하도록 합니다. 응답이 손실된 요청이 다시 전달되므로 요청 ID당 콜백을 멱등성으로 만드세요. Claude Code v2.1.195 이상이 필요합니다 |

645| `supportedCommands()` | 사용 가능한 명령어를 반환합니다. 에이전트 SDK v0.3.216부터 목록은 중간 세션 명령어 변경을 반영합니다. [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage)를 참조하세요 |647| `supportedCommands()` | 사용 가능한 명령어를 반환합니다. 에이전트 SDK v0.3.216부터 목록은 중간 세션 명령어 변경을 반영합니다. [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage)를 참조하세요 |

646| `supportedModels()` | 표시 정보가 있는 사용 가능한 모델을 반환합니다 |648| `supportedModels()` | 표시 정보가 있는 사용 가능한 모델을 반환합니다 |

647| `supportedAgents()` | [`AgentInfo`](#agentinfo)`[]`로 사용 가능한 서브에이전트를 반환합니다 |649| `supportedAgents()` | [`AgentInfo`](#agentinfo)`[]`로 사용 가능한 서브에이전트를 반환합니다 |

648| `mcpServerStatus()` | 연결된 MCP 서버의 상태를 반환합니다 |650| `mcpServerStatus()` | 연결된 MCP 서버의 상태를 [`McpServerStatus`](#mcpserverstatus)`[]`로 반환합니다 |

649| `getContextUsage(opts?)` | 세션의 컨텍스트 창 사용량을 카테고리, 스킬 및 도구별로 분류하는 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)를 반환합니다. 기본 `detail`을 사용하면 대화형 세션에서 `/context`가 표시하는 것과 동일한 데이터이므로 토큰 수와 함께 Claude Code가 `/context` 사용량 그리드를 그리는 데 사용하는 `color` 및 `gridRows` 같은 표시 필드를 전달합니다. [`detail` 옵션](#sdkcontrolgetcontextusageresponse)은 에이전트 SDK v0.3.257 이상이 필요합니다 |651| `getContextUsage(opts?)` | 세션의 컨텍스트 창 사용량을 카테고리, 스킬 및 도구별로 분류하는 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)를 반환합니다. 기본 `detail`을 사용하면 대화형 세션에서 `/context`가 표시하는 것과 동일한 데이터이므로 토큰 수와 함께 Claude Code가 `/context` 사용량 그리드를 그리는 데 사용하는 `color` 및 `gridRows` 같은 표시 필드를 전달합니다. [`detail` 옵션](#sdkcontrolgetcontextusageresponse)은 에이전트 SDK v0.3.257 이상이 필요합니다 |

650| `readFile(path, options?)` | 세션의 파일 시스템에서 파일을 읽습니다. Claude Code는 경로를 `cwd`에 대해 해결합니다. [readFile()이 읽을 수 있는 것](#what-readfile-can-read)은 제공하는 파일을 나열합니다. 읽기 상한을 변경하려면 `{ maxBytes }`를 전달하세요(기본값 1 MB, 상한 10 MB). 이미지 같은 바이너리 파일의 경우 `{ encoding: 'base64' }`를 전달하세요. 권한 거부, 누락된 파일 또는 전송 오류 시 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 또는 `null`로 해결됩니다. TypeScript SDK v0.2.121 이상이 필요합니다 |652| `readFile(path, options?)` | 세션의 파일 시스템에서 파일을 읽습니다. Claude Code는 경로를 `cwd`에 대해 해결합니다. [readFile()이 읽을 수 있는 것](#what-readfile-can-read)은 제공하는 파일을 나열합니다. 읽기 상한을 변경하려면 `{ maxBytes }`를 전달하세요(기본값 1 MB, 상한 10 MB). 이미지 같은 바이너리 파일의 경우 `{ encoding: 'base64' }`를 전달하세요. 권한 거부, 누락된 파일 또는 전송 오류 시 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 또는 `null`로 해결됩니다. TypeScript SDK v0.2.121 이상이 필요합니다 |

651| `reloadSkills()` | 디스크에서 스킬을 다시 로드하여 중간 세션에서 추가하거나 편집한 스킬을 실행 중인 세션에서 사용할 수 있도록 합니다. 다시 로드 후 사용 가능한 스킬을 나열하는 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse)로 해결됩니다. 에이전트 SDK v0.3.163 이상이 필요합니다 |653| `reloadSkills()` | 디스크에서 스킬을 다시 로드하여 중간 세션에서 추가하거나 편집한 스킬을 실행 중인 세션에서 사용할 수 있도록 합니다. 다시 로드 후 사용 가능한 스킬을 나열하는 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse)로 해결됩니다. 에이전트 SDK v0.3.163 이상이 필요합니다 |

653| `reconnectMcpServer(serverName)` | 이름으로 MCP 서버를 다시 연결합니다. 이름이 `.mcp.json` 또는 `~/.claude.json` 같은 설정 파일의 항목과도 일치하면 Claude Code는 설정 파일 항목이 아닌 [`mcpServers`](#options) 또는 `setMcpServers()`를 통해 구성한 서버를 다시 연결합니다. 해당 해결 순서는 Claude Code v2.1.257 이상이 필요합니다 |655| `reconnectMcpServer(serverName)` | 이름으로 MCP 서버를 다시 연결합니다. 이름이 `.mcp.json` 또는 `~/.claude.json` 같은 설정 파일의 항목과도 일치하면 Claude Code는 설정 파일 항목이 아닌 [`mcpServers`](#options) 또는 `setMcpServers()`를 통해 구성한 서버를 다시 연결합니다. 해당 해결 순서는 Claude Code v2.1.257 이상이 필요합니다 |

654| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 해결을 사용하여 이름으로 MCP 서버를 활성화 또는 비활성화합니다. 비활성화하면 서버를 연결 해제합니다 |656| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()`와 동일한 이름 해결을 사용하여 이름으로 MCP 서버를 활성화 또는 비활성화합니다. 비활성화하면 서버를 연결 해제합니다 |

655| `setMcpServers(servers)` | 이 세션의 MCP 서버 집합을 동적으로 대체합니다. 추가되고 제거된 서버 및 오류를 명시하는 [`McpSetServersResult`](#mcpsetserversresult)로 해결됩니다 |657| `setMcpServers(servers)` | 이 세션의 MCP 서버 집합을 동적으로 대체합니다. 추가되고 제거된 서버 및 오류를 명시하는 [`McpSetServersResult`](#mcpsetserversresult)로 해결됩니다 |

658| `readMcpResource(serverName, uri)` | *알파.* 연결된 MCP 서버에서 하나의 MCP Apps `ui://` 리소스를 읽어 애플리케이션이 도구의 위젯을 렌더링할 수 있도록 합니다. [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse)로 해결됩니다. TypeScript 에이전트 SDK v0.3.280 이상이 필요합니다 |

656| `streamInput(stream)` | 다중 턴 대화를 위해 쿼리에 입력 메시지를 스트리밍합니다 |659| `streamInput(stream)` | 다중 턴 대화를 위해 쿼리에 입력 메시지를 스트리밍합니다 |

657| `stopTask(taskId)` | ID로 실행 중인 백그라운드 작업을 중지합니다 |660| `stopTask(taskId)` | ID로 실행 중인 백그라운드 작업을 중지합니다 |

658| `close()` | 쿼리를 닫고 기본 프로세스를 종료합니다. 쿼리를 강제로 종료하고 모든 리소스를 정리합니다 |661| `close()` | 쿼리를 닫고 기본 프로세스를 종료합니다. 쿼리를 강제로 종료하고 모든 리소스를 정리합니다 |

673 676 

674값은 플래그 설정 계층에 작성되며, 이는 시작 시 `query()`의 인라인 `settings` 옵션이 채우는 계층과 동일합니다. 이는 [온페이지 우선 순위 섹션](#settings-precedence)이 프로그래밍 옵션이라고 부르는 계층과 동일합니다.677값은 플래그 설정 계층에 작성되며, 이는 시작 시 `query()`의 인라인 `settings` 옵션이 채우는 계층과 동일합니다. 이는 [온페이지 우선 순위 섹션](#settings-precedence)이 프로그래밍 옵션이라고 부르는 계층과 동일합니다.

675 678 

676연속 호출은 최상위 키를 얕게 병합합니다. `{ permissions: {...} }` 포함 두 번째 호출은 이전 호출의 전체 `permissions` 객체를 깊게 병합하는 대신 대체합니다. 플래그 계층에서 키를 지우려면 해당 키에 `null`을 전달하세요. 그러면 대부분의 키가 낮은 우선 순위 소스로 폴백됩니다. 지워진 `model`은 설정 파일이 `model`을 설정하더라도 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다. `undefined`를 전달하면 JSON 직렬화가 이를 삭제하므로 효과가 없습니다.679연속 호출은 최상위 키를 얕게 병합합니다. `{ permissions: {...} }` 포함 두 번째 호출은 이전 호출의 전체 `permissions` 객체를 깊게 병합하는 대신 대체합니다.

680 

681플래그 계층에서 키를 지우려면 해당 키에 `null`을 전달하세요. 그러면 대부분의 키가 먼저 시작 시 `query()`의 `settings` 옵션이 설정한 값으로 폴백한 다음 낮은 우선 순위 소스로 폴백합니다. 지워진 `model`은 설정 파일이 `model`을 설정하더라도 [Claude Code의 기본 모델](/docs/ko/model-config)로 재설정됩니다. `undefined`를 전달하면 JSON 직렬화가 이를 삭제하므로 효과가 없습니다.

682 

683`model` 외에 세 가지 키는 폴백하는 대신 세션 상태를 재설정합니다:

684 

685* `effortLevel: null`은 설정 파일의 `effortLevel`이 아닌 모델의 기본 노력 수준으로 세션을 반환합니다. `query()`의 `effort` 옵션도 복원하지 않습니다.

686* `agent: null`은 다음 턴부터 메인 스레드를 에이전트 없이 실행합니다. 설정 파일의 `agent`도 복원하지 않습니다. 지워진 에이전트가 자신의 모델을 적용했으면 세션은 시작 시 해결한 모델로 돌아갑니다.

687* `ultracode: null`은 `false`처럼 ultracode를 끕니다. 설정 파일의 `ultracode` 값을 복원하지 않습니다. 세션은 현재 노력 수준을 유지하므로 같은 호출에서 `effortLevel`을 전달하여 변경하세요.

677 688 

678스트리밍 입력 모드에서만 사용 가능하며, 이는 `setModel()` 및 `setPermissionMode()`와 동일한 제약입니다.689스트리밍 입력 모드에서만 사용 가능하며, 이는 `setModel()` 및 `setPermissionMode()`와 동일한 제약입니다.

679 690 

695 `applyFlagSettings()`는 TypeScript 전용입니다. Python SDK는 동등한 메서드를 노출하지 않습니다.706 `applyFlagSettings()`는 TypeScript 전용입니다. Python SDK는 동등한 메서드를 노출하지 않습니다.

696</Note>707</Note>

697 708 

709<h4 id="updatesettings">

710 `updateSettings()`

711</h4>

712 

713설정을 디스크의 설정 파일에 작성하여 값이 나중 세션에 지속되도록 합니다. 각 소스는 하나의 키를 허용하며, 문자열 값을 가집니다:

714 

715* **`"localSettings"`**: `outputStyle`을 허용하고 프로젝트의 로컬 설정 파일 `.claude/settings.local.json`에 병합합니다. 새 스타일은 세션의 다음 요청에서 적용됩니다.

716* **`"userSettings"`**: `effortLevel`을 허용하고 세션의 현재 모델에 대한 기본 [노력 수준](/docs/ko/model-config#adjust-effort-level)으로 사용자 설정 파일의 [`modelSettings`](/docs/ko/settings-reference#modelsettings) 아래에 저장합니다. `max`를 전달하면 아무것도 작성되지 않습니다. `max`는 세션 전용이기 때문입니다. 실행 중인 세션은 어느 쪽이든 현재 노력 수준을 유지하므로 변경하려면 [`applyFlagSettings()`](#applyflagsettings)를 호출하세요. 이 소스는 TypeScript SDK v0.3.277 이상이 필요하며, Claude Code v2.1.277을 번들합니다.

717 

718호출은 요청이 다른 키를 전달할 때, 세션이 원격 전송을 통해 실행될 때, 세션의 [`settingSources`](#options)가 명시한 소스를 제외할 때 거부됩니다. 키 삭제는 지원되지 않습니다.

719 

698<h3 id="warmquery">720<h3 id="warmquery">

699 `WarmQuery`721 `WarmQuery`

700</h3>722</h3>

942 964 

943`skills`는 다시 로드 후 사용 가능한 스킬을 나열하며, `supportedCommands()`가 반환하는 것과 동일한 [`SlashCommand`](#slashcommand) 형태입니다.965`skills`는 다시 로드 후 사용 가능한 스킬을 나열하며, `supportedCommands()`가 반환하는 것과 동일한 [`SlashCommand`](#slashcommand) 형태입니다.

944 966 

967<h3 id="sdkcontrolmcpreadresourceresponse">

968 `SDKControlMcpReadResourceResponse`

969</h3>

970 

971[`readMcpResource()`](#query-object)의 반환 유형으로, MCP 서버의 `resources/read` 결과를 전달합니다. TypeScript 에이전트 SDK v0.3.280 이상이 필요합니다.

972 

973```typescript theme={null}

974type SDKControlMcpReadResourceResponse = {

975 contents: {

976 uri: string;

977 mimeType?: string;

978 text?: string;

979 blob?: string;

980 _meta?: Record<string, unknown>;

981 }[];

982};

983```

984 

985`readMcpResource()`에 `mcpServerStatus()`가 보고하는 서버 이름과 `ui://` URI(예: 도구가 [`_meta`](#mcpserverstatus)에서 선언하는 `ui.resourceUri`)를 전달하세요. 호출은 다른 URI 스킴, 애플리케이션이 자체 호스팅하는 [SDK MCP 서버](#createsdkmcpserver), 연결되지 않은 서버에 대해 거부됩니다. init 메시지의 [`capabilities`](#sdksystemmessage)에 `mcp_read_resource_v1`이 포함될 때 사용 가능합니다.

986 

987각 `contents` 항목은 서버가 보낸 하나의 콘텐츠 항목입니다. `blob`은 바이너리 항목의 base64 데이터를 보유하고, `_meta`는 항목 자체의 `_meta`이며, MCP Apps 서버는 리소스의 `ui.csp` 및 `ui.permissions`를 여기에 넣습니다. 콘텐츠는 신뢰할 수 없는 제3자 HTML이므로 샌드박스에서 렌더링하세요.

988 

945<h3 id="agentdefinition">989<h3 id="agentdefinition">

946 `AgentDefinition`990 `AgentDefinition`

947</h3>991</h3>

1275 `SDKMessage`1319 `SDKMessage`

1276</h3>1320</h3>

1277 1321 

1278쿼리에서 반환된 모든 가능한 메시지의 합집합 타입입니다.1322쿼리에서 반환되는 모든 가능한 메시지의 합집합 타입입니다.

1279 1323 

1280```typescript theme={null}1324```typescript theme={null}

1281type SDKMessage =1325type SDKMessage =

1328 type: "assistant";1372 type: "assistant";

1329 uuid: UUID;1373 uuid: UUID;

1330 session_id: string;1374 session_id: string;

1331 message: BetaMessage; // Anthropic SDK에서1375 message: BetaMessage; // From Anthropic SDK

1332 parent_tool_use_id: string | null;1376 parent_tool_use_id: string | null;

1333 error?: SDKAssistantMessageError;1377 error?: SDKAssistantMessageError;

1334 aborted?: true;1378 aborted?: true;

1339};1383};

1340```1384```

1341 1385 

1342`message` 필드는 Anthropic SDK의 [`BetaMessage`](https://platform.claude.com/docs/ko/api/messages/create)입니다. `id`, `content`, `model`, `stop_reason` 및 `usage`와 같은 필드를 포함합니다.1386`message` 필드는 Anthropic SDK의 [`BetaMessage`](https://platform.claude.com/docs/en/api/messages/create)입니다. `id`, `content`, `model`, `stop_reason`, `usage` 같은 필드를 포함합니다.

1343 1387 

1344`SDKAssistantMessageError`는 다음 중 하나입니다: `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'` 또는 `'unknown'`. 이 중 네 가지 값은 이름이 말하는 것보다 더 많은 의미를 가집니다:1388`SDKAssistantMessageError`는 다음 중 하나입니다: `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'`, 또는 `'unknown'`. 이 중 네 개의 값은 이름이 나타내는 것보다 더 많은 의미를 가집니다:

1345 1389 

1346* `'model_not_found'`: 선택한 모델이 존재하지 않거나 계정 또는 배포에서 사용할 수 없습니다.1390* `'model_not_found'`: 선택한 모델이 존재하지 않거나 계정이나 배포에서 사용할 수 없음

1347* `'overloaded'`: API가 서버가 용량에 도달했기 때문에 529를 반환했습니다. 할당량에 대한 429인 `'rate_limit'`과는 다릅니다.1391* `'overloaded'`: API가 서버가 용량에 도달했기 때문에 529를 반환했으며, 할당량에 대한 429인 `'rate_limit'`과는 다름

1348* `'account_on_hold'`: [계정이 보류 중입니다](/docs/ko/errors#your-account-is-on-hold)1392* `'account_on_hold'`: [계정이 보류 중](/docs/ko/errors#your-account-is-on-hold)

1349* `'cloud_credential_error'`: Claude Code가 실행되는 머신에서 사용 가능한 AWS 또는 Google Cloud 자격 증명을 얻을 수 없어서 클라우드 제공자에게 요청이 도달하지 않았습니다. 일반적인 원인은 해당 머신에서 만료되었거나 완료되지 않은 클라우드 로그인이지만, 일시적으로 도달할 수 없는 자격 증명 서비스도 동일한 값을 보고합니다. [AWS 또는 Google Cloud 자격 증명을 로드할 수 없음](/docs/ko/errors#could-not-load-aws-or-google-cloud-credentials)을 참조하십시오. TypeScript Agent SDK v0.3.267 이상이 필요하며, Claude Code v2.1.267을 번들로 제공합니다.1393* `'cloud_credential_error'`: Claude Code가 실행되는 머신에서 사용 가능한 AWS 또는 Google Cloud 자격증명을 얻을 수 없어서 클라우드 제공자에게 요청이 도달하지 않았습니다. 일반적인 원인은 해당 머신에서 만료되었거나 완료되지 않은 클라우드 로그인이지만, 일시적으로 도달할 수 없는 자격증명 서비스도 동일한 값을 보고합니다. [AWS 또는 Google Cloud 자격증명을 로드할 수 없음](/docs/ko/errors#could-not-load-aws-or-google-cloud-credentials)을 참조하세요. TypeScript Agent SDK v0.3.267 이상 필요하며, Claude Code v2.1.267을 번들로 포함합니다.

1350 1394 

1351`aborted`는 중단 또는 중지가 스트림이 완료되기 전에 어시스턴트 메시지를 자를 때 `true`입니다: 메시지에는 `stop_reason`이 없으며 콘텐츠는 단어 중간에 끝날 수 있습니다. 이 필드는 정상적으로 완료된 메시지에는 없습니다. Agent SDK v0.3.214 이상이 필요합니다.1395`aborted`는 인터럽트 또는 중단이 스트림이 완료되기 전에 어시스턴트 메시지를 잘랐을 때 `true`입니다: 메시지에는 `stop_reason`이 없고 콘텐츠가 단어 중간에 끝날 수 있습니다. 이 필드는 정상적으로 완료된 메시지에는 없습니다. Agent SDK v0.3.214 이상이 필요합니다.

1352 1396 

1353Claude Code는 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid` 및 `user_message_uuids`를 설정합니다.1397Claude Code는 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다.

1354 1398 

1355`timestamp`는 메시지의 콘텐츠가 생성을 완료한 프로세스의 머신 시간입니다. 값은 해당 머신의 시계에서 나오므로 표시 목적으로만 사용하고 메시지를 순서대로 정렬하지 마십시오. 하나의 API 턴은 동일한 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각각 자신의 `timestamp`를 가집니다. 필드가 없으면 메시지를 받은 시간으로 돌아갑니다.1399`timestamp`는 메시지의 콘텐츠가 생성을 완료한 ISO 8601 시간입니다. 값은 해당 머신의 시계에서 나오므로 표시 목적으로만 사용하고 메시지를 순서대로 정렬하지 마세요. 하나의 API 턴은 동일한 `message.id`를 공유하지만 각각 고유한 `timestamp`를 가진 여러 어시스턴트 메시지를 생성할 수 있습니다. 필드가 없으면 메시지를 받은 시간으로 돌아가세요.

1356 1400 

1357`context_usage`는 `/context` 보고서의 구조화된 복사본이며, [`SDKContextUsage`](#sdkcontextusage)로 입력되고 Agent SDK v0.3.232 이상이 필요합니다. 프롬프트로 `/context`를 보낼 때, Claude Code는 보고서를 `message.content`가 마크다운 테이블을 보유하는 어시스턴트 메시지로 전달하고 `context_usage`를 동일한 메시지에 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 필드를 설정하지 않으며, 이전 버전은 `/context` 테이블을 없이 전달하므로 필드가 있을 때 분석을 읽고 없을 때 마크다운 텍스트로 돌아갑니다.1401`context_usage`는 `/context` 보고서의 구조화된 복사본이며, [`SDKContextUsage`](#sdkcontextusage)로 입력되고 Agent SDK v0.3.232 이상이 필요합니다. 프롬프트로 `/context`를 보낼 때, Claude Code는 보고서를 어시스턴트 메시지로 전달하며, 그 `message.content`는 마크다운 테이블을 보유하고, 동일한 메시지에 `context_usage`를 첨부합니다. Claude Code는 다른 어시스턴트 메시지에는 필드를 설정하지 않으며, 이전 버전은 `/context` 테이블을 없이 전달하므로, 필드가 있을 때 분석을 읽고 없을 때 마크다운 텍스트로 돌아가세요.

1358 1402 

1359<h3 id="sdkusermessage">1403<h3 id="sdkusermessage">

1360 `SDKUserMessage`1404 `SDKUserMessage`

1367 type: "user";1411 type: "user";

1368 uuid?: UUID;1412 uuid?: UUID;

1369 session_id?: string;1413 session_id?: string;

1370 message: MessageParam; // Anthropic SDK에서1414 message: MessageParam; // From Anthropic SDK

1415 pasted_content?: MessageParam["content"][];

1371 parent_tool_use_id: string | null;1416 parent_tool_use_id: string | null;

1372 isSynthetic?: boolean;1417 isSynthetic?: boolean;

1373 shouldQuery?: boolean;1418 shouldQuery?: boolean;

1374 tool_use_result?: unknown;1419 tool_use_result?: unknown;

1375 origin?: SDKMessageOrigin;1420 origin?: SDKMessageOrigin;

1421 inline_pastes?: string[];

1376};1422};

1377```1423```

1378 1424 

1425사용자가 입력 UI에 붙여넣은 콘텐츠를 입력한 것이 아니라 보내도록 `pasted_content`를 설정하고, 붙여넣기당 하나의 항목을 설정하며, 각각은 문자열 또는 콘텐츠 블록의 배열입니다. Claude Code는 각 항목의 텍스트를 입력된 텍스트 뒤에 순서대로 추가하고, 각 붙여넣기를 `<pasted_content>` 태그로 감쌀 수 있습니다. 텍스트 이외의 블록은 무시되므로 이미지와 문서는 `message.content`에서 보내세요. Agent SDK v0.3.277 이상이 필요합니다.

1426 

1379`shouldQuery`를 `false`로 설정하여 어시스턴트 턴을 트리거하지 않고 메시지를 트랜스크립트에 추가합니다. 메시지는 보류되고 턴을 트리거하는 다음 사용자 메시지로 병합됩니다. 이를 사용하여 모델 호출을 소비하지 않고 대역 외에서 실행한 명령의 출력과 같은 컨텍스트를 주입합니다.1427`shouldQuery`를 `false`로 설정하여 어시스턴트 턴을 트리거하지 않고 메시지를 트랜스크립트에 추가합니다. 메시지는 보류되고 턴을 트리거하는 다음 사용자 메시지로 병합됩니다. 이를 사용하여 모델 호출을 소비하지 않고 대역 외에서 실행한 명령의 출력과 같은 컨텍스트를 주입합니다.

1380 1428 

1381도구 결과 블록을 전달하는 메시지에서 `tool_use_result`는 모델에 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 해당 형태는 일치하는 `tool_use` 블록으로 명명된 도구에 따라 달라지므로 필드는 `unknown`으로 입력됩니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types)에 나열되어 있습니다.1429`tool_result` 블록을 전달하는 메시지에서 `tool_use_result`는 모델로 전송된 텍스트가 아니라 도구의 구조화된 출력 객체입니다. 해당 형태는 일치하는 `tool_use` 블록으로 명명된 도구에 따라 다르므로 필드는 `unknown`으로 입력됩니다. 기본 제공 형태는 [도구 출력 타입](#tool-output-types) 아래에 나열되어 있습니다.

1382 1430 

1383`Agent` 도구의 경우 `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `completed` 결과에서 `content`는 Claude Code가 `tool_result` 텍스트에 추가하는 에이전트 ID 및 사용량 트레일러 없이 서브에이전트의 보고서를 보유합니다. 따라서 해당 텍스트를 파싱하는 대신 `tool_use_result`에서 렌더링합니다.1431`Agent` 도구의 경우 `tool_use_result`는 [`AgentOutput`](#agent-2)입니다. `completed` 결과에서 `content`는 Claude Code가 `tool_result` 텍스트에 추가하는 에이전트 ID 및 사용량 트레일러 없이 서브에이전트의 보고서를 보유하므로 해당 텍스트를 구문 분석하는 대신 `tool_use_result`에서 렌더링합니다.

1384 1432 

1385결과에 `resource_link` 블록이 포함된 MCP 도구의 경우, `tool_use_result`는 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 항목의 `resourceLinks` 배열을 가진 객체입니다. Claude는 각 링크를 `tool_result` 블록의 텍스트 줄로 받으므로 서버가 반환한 파일을 렌더링하기 위해 `resourceLinks`를 읽고 해당 텍스트를 파싱하지 마십시오. Claude Code는 결과에 링크가 없을 때 `resourceLinks`를 생략하고 서브에이전트의 결과에서 생략하며, 결과당 최대 50개의 링크를 유지하고 배열이 직렬화된 JSON의 64 KiB에 도달하면 링크 추가를 중지합니다. `resourceLinks`는 Agent SDK v0.3.257 이상이 필요합니다.1433결과에 `resource_link` 블록이 포함된 MCP 도구의 경우 `tool_use_result`는 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 항목의 `resourceLinks` 배열을 가진 객체입니다. Claude는 각 링크를 `tool_result` 블록의 텍스트 줄로 받으므로 해당 텍스트를 구문 분석하는 대신 `resourceLinks`를 읽어 서버가 반환한 파일을 렌더링합니다. Claude Code는 결과에 링크가 없을 때 `resourceLinks`를 생략하고 서브에이전트의 결과에서 생략하며, 결과당 최대 50개의 링크를 유지하고, 배열이 64 KiB의 직렬화된 JSON에 도달하면 링크 추가를 중지합니다. `resourceLinks`는 Agent SDK v0.3.257 이상이 필요합니다.

1434 

1435사용자가 입력한 것이 아니라 붙여넣은 `message.content`의 부분을 알려주도록 `inline_pastes`를 설정하고, 붙여넣기당 하나의 문자열을 설정합니다. 프롬프트 텍스트는 사용자가 배치한 위치에 유지됩니다. Claude Code는 각 나열된 붙여넣기를 `<pasted_content>` 태그로 감쌀 수 있으므로 Claude는 붙여넣은 자료를 사용자 자신의 단어와 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록의 붙여넣기만 래핑됩니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

1386 1436 

1387<h3 id="sdkusermessagereplay">1437<h3 id="sdkusermessagereplay">

1388 `SDKUserMessageReplay`1438 `SDKUserMessageReplay`

1389</h3>1439</h3>

1390 1440 

1391필수 UUID를 포함한 재생된 사용자 메시지입니다.1441필수 UUID가 있는 재생된 사용자 메시지입니다.

1392 1442 

1393```typescript theme={null}1443```typescript theme={null}

1394type SDKUserMessageReplay = {1444type SDKUserMessageReplay = {

1404};1454};

1405```1455```

1406 1456 

1407세션 외부에서 주입된 사용자 턴으로, [`origin`](#sdkmessageorigin) 종류가 `peer` 또는 `channel`인 경우, 활성 턴 중에 전달되었는지 또는 세션이 유휴 상태일 때 새 턴을 시작했는지 여부에 관계없이 스트림에 재생으로 도달합니다. v2.1.207 이전에는 세션이 유휴 상태일 때 전달된 주입된 턴이 스트림에서 메시지를 생성하지 않았으며 트랜스크립트를 다시 읽을 때만 나타났습니다.1457세션 외부에서 주입된 사용자 턴으로, [`origin`](#sdkmessageorigin) 종류가 `peer` 또는 `channel`인 턴은 활성 턴 중에 전달되었는지 또는 세션이 유휴 상태일 때 새 턴을 시작했는지 여부에 관계없이 재생으로 스트림에 도달합니다. v2.1.207 이전에는 세션이 유휴 상태일 때 전달된 주입된 턴이 스트림에 메시지를 생성하지 않았고 트랜스크립트를 다시 읽을 때만 나타났습니다.

1408 1458 

1409<h3 id="sdkresultmessage">1459<h3 id="sdkresultmessage">

1410 `SDKResultMessage`1460 `SDKResultMessage`

1479 1529 

1480결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:1530결과의 여러 필드는 `subtype` 이상의 진단 세부 정보를 전달합니다:

1481 1531 

1482* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. API 오류 없이 턴이 종료되었을 때는 없거나 `null`입니다.1532* `api_error_status`: 대화를 종료한 API 오류의 HTTP 상태 코드입니다. 턴이 API 오류 없이 끝났을 때 없거나 `null`입니다.

1483* `ttft_ms`: 첫 번째 토큰까지의 시간(밀리초)입니다. 첫 번째 완전한 어시스턴트 메시지가 도착할 때 측정됩니다. 성공 경로에만 표시됩니다.1533* `ttft_ms`: 첫 번째 완전한 어시스턴트 메시지가 도착할 때 측정된 밀리초 단위의 첫 번째 토큰까지의 시간입니다. 성공 분기에만 있습니다.

1484* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 시간(밀리초)입니다. `ttft_ms`보다 낮습니다. 두 시간 사이의 간격은 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 경로에만 표시됩니다.1534* `ttft_stream_ms`: 응답 스트림이 열릴 때 첫 번째 `message_start` 스트림 이벤트까지의 밀리초 단위 시간입니다. `ttft_ms`보다 낮습니다. 두 사이의 간격은 첫 번째 메시지를 스트리밍하는 데 소요된 시간입니다. 성공 분기에만 있습니다.

1485* `user_message_uuid`: 이 턴이 답한 메시지를 보낸 메시지의 `uuid`입니다. 어떤 결과가 이를 전달하는지는 [`user_message_uuid`](#user_message_uuid)를 참조하십시오.1535* `user_message_uuid`: 이 턴이 답변한 메시지의 `uuid`입니다. 어떤 결과가 이를 전달하는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.

1486* `user_message_uuids`: 이 턴에서 Claude Code가 답한 보낸 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하십시오.1536* `user_message_uuids`: Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.

1487* `request_sent_wall_ms`: Claude Code가 API 요청을 발송한 에포크 밀리초입니다. 서버 측 타임스탬프와 조인하기 위해 사용됩니다. [`user_message_uuid`](#user_message_uuid)와 함께만 표시되며, `is_error` false인 성공 결과에서 턴이 API 요청을 보냈을 때만 표시됩니다.1537* `request_sent_wall_ms`: Claude Code가 API 요청을 발송한 에포크 밀리초로, 서버 측 타임스탬프와 조인하기 위한 것입니다. [`user_message_uuid`](#user_message_uuid)와 함께만 있으며, `is_error` false인 성공 결과에서 턴이 API 요청을 보냈을 때만 있습니다.

1488* `first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 시간(밀리초)입니다. 생각 블록을 콘텐츠로 계산합니다. 성공 경로에만 표시되며, `is_error`가 false일 때만 표시됩니다. Agent SDK v0.3.260 이상이 필요합니다.1538* `first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 밀리초 단위 시간으로, 생각 블록을 콘텐츠로 계산합니다. 성공 분기에만 있으며, `is_error`가 false일 때만 있습니다. Agent SDK v0.3.260 이상이 필요합니다.

1489* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: 턴의 첫 번째 스트림 이벤트를 업로드하기 위한 타이밍입니다. Claude Code는 [클라우드 세션](/docs/ko/claude-code-on-the-web)과 같이 claude.ai로 스트리밍하는 세션에서만 기록하며, `query()`가 생성하는 결과는 이를 전달하지 않습니다. Agent SDK v0.3.260 이상이 필요합니다.1539* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: 턴의 첫 번째 스트림 이벤트를 업로드하기 위한 타이밍입니다. Claude Code는 [클라우드 세션](/docs/ko/claude-code-on-the-web)과 같이 claude.ai로 스트리밍하는 세션에서만 기록하며, `query()`가 생성하는 결과는 이를 전달하지 않습니다. Agent SDK v0.3.260 이상이 필요합니다.

1490* `usage`: 메인 에이전트 루프만 해당합니다. 서브에이전트 및 보조 모델 호출을 제외하며, 스트리밍 입력 세션에서는 턴당입니다. 토큰/비용 회계를 위해 `modelUsage`를 선호합니다.1540* `usage`: 메인 에이전트 루프만 해당합니다. 서브에이전트 및 보조 모델 호출을 제외하며, 스트리밍 입력 세션에서는 턴당입니다. 토큰/비용 회계를 위해 `modelUsage`를 선호합니다.

1491* `modelUsage`: 이 `query()` 호출 중에 쿼리 파이프라인을 통해 수행된 모든 모델 호출에 대한 모델별 합계입니다. 메인 루프, 서브에이전트 및 압축 및 Workflow 에이전트와 같은 내부 호출을 포함합니다. 권한 분류자 및 토큰 계산 요청과 같은 해당 파이프라인 외부의 도우미 호출은 제외됩니다. 스트리밍 입력 세션에서 합계는 턴 전체에 누적되므로 결과 전체에서 합산하는 대신 최신 결과를 읽습니다. 재설정에 대해서는 [스트리밍 입력 모드에서 비용 추적](/docs/ko/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)을 참조하고, 0으로 설정된 결과에 대해서는 [세션 충돌 후 합계 복구](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)를 참조하십시오.1541* `modelUsage`: 이 `query()` 호출 중에 쿼리 파이프라인을 통해 수행된 모든 모델 호출에 대한 모델별 합계로, 메인 루프, 서브에이전트, 압축 및 Workflow 에이전트와 같은 내부 호출을 포함합니다. 권한 분류자 및 토큰 계산 요청과 같은 해당 파이프라인 외부의 도우미 호출은 제외됩니다. 세션을 재개하는 호출은 [세션의 이전 호출에서 복원된 모델별 합계](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)도 계산합니다. 스트리밍 입력 세션에서 합계는 턴 전체에 누적되므로 결과 전체에서 합산하는 대신 최신 결과를 읽으세요. 재설정에 대해서는 [스트리밍 입력 모드에서 비용 추적](/docs/ko/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)을 참조하고 0으로 설정된 결과에 대해서는 [세션 충돌 후 합계 복구](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)를 참조하세요.

1492* `total_cost_usd`: 이 `query()` 호출에 대한 누적 예상 비용(USD)입니다. `modelUsage`와 동일한 호출을 포함하고 동일한 지점에서 재설정됩니다. 이는 추정치이지 청구 명세서가 아닙니다. 정확도 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하십시오.1542* `total_cost_usd`: USD의 누적 예상 비용으로, `modelUsage`와 동일한 호출을 포함하고 동일한 지점에서 재설정됩니다. 세션을 재개하는 호출은 [세션의 이전 호출에서 복원된 합계](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)도 계산합니다. 이는 청구 명세서가 아닌 추정치입니다. 정확도 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요.

1493* `queued_turn_count`: Claude Code가 결과를 생성했을 때 `origin: { kind: "human" }`으로 보낸 메시지 중 여전히 대기 중인 메시지의 수입니다. `0`과 없는 필드가 무엇을 말하는지는 [`queued_turn_count`](#queued_turn_count)를 참조하십시오.1543* `queued_turn_count`: Claude Code가 결과를 생성했을 때 여전히 대기 중인 `origin: { kind: "human" }`으로 보낸 메시지의 수입니다. `0`과 없는 필드가 무엇을 의미하는지는 [`queued_turn_count`](#queued_turn_count)를 참조하세요.

1494* `startup_failure_reason`: Claude Code가 시작을 거부한 이유입니다. 알려진 시작 실패에서 종료하기 전에 작성하는 `error_during_execution` 결과에서 설정됩니다. 값 및 어떤 실패가 이를 전달하는지는 [`startup_failure_reason`](#startup_failure_reason)을 참조하십시오. Agent SDK v0.3.274 이상이 필요합니다.1544* `startup_failure_reason`: Claude Code가 시작을 거부한 이유로, 알려진 시작 실패 전에 작성하는 `error_during_execution` 결과에서 확인할 수 있습니다. 값과 어떤 실패가 이를 전달하는지는 [`startup_failure_reason`](#startup_failure_reason)을 참조하세요. Agent SDK v0.3.274 이상이 필요합니다.

1495* `terminal_reason`: 루프가 종료된 이유입니다. `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"` 또는 `"turn_setup_failed"` 중 하나입니다.1545* `terminal_reason`: 루프가 끝난 이유입니다. `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, 또는 `"turn_setup_failed"` 중 하나입니다.

1496* `fast_mode_state`: `"on"`, `"off"` 또는 `"cooldown"` 중 하나입니다.1546* `fast_mode_state`: `"on"`, `"off"`, 또는 `"cooldown"` 중 하나입니다.

1497* `fast_mode_disabled_reason`: [빠른 모드](/docs/ko/fast-mode)를 지금 사용할 수 없는 이유입니다. 빠른 모드를 차단하는 것이 없으면 없습니다. 하지만 요청이 여전히 표준 속도로 실행될 수 있습니다. 빠른 모드 속도 제한 후 쿨다운 중에 Claude Code는 `fast_mode_state: "cooldown"`을 이유 코드 없이 보고하고 쿨다운이 만료되면 빠른 모드를 다시 활성화합니다. Claude Code v2.1.219 이상이 필요합니다.1547* `fast_mode_disabled_reason`: [빠른 모드](/docs/ko/fast-mode)를 지금 사용할 수 없는 이유입니다. 빠른 모드를 차단하는 것이 없을 때는 없지만, 요청이 여전히 표준 속도로 실행될 수 있습니다. 빠른 모드 속도 제한 후 쿨다운 중에 Claude Code는 이유 코드 없이 `fast_mode_state: "cooldown"`을 보고하고 쿨다운이 만료되면 빠른 모드를 다시 활성화합니다. Claude Code v2.1.219 이상이 필요합니다.

1498 1548 

1499이유 코드를 사용하여 자신의 UI에서 빠른 모드가 꺼진 이유를 설명하는 대신 가용성을 다시 파생시킵니다. 각 코드는 빠른 모드를 차단한 검사의 이름을 지정합니다:1549이유 코드를 사용하여 자신의 UI에서 빠른 모드가 꺼진 이유를 설명하는 대신 가용성을 다시 도출합니다. 각 코드는 빠른 모드를 차단한 검사의 이름을 지정합니다:

1500 1550 

1501| 이유 코드 | 의미 |1551| 이유 코드 | 의미 |

1502| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |1552| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |

1503| `free` | 계정에 빠른 모드가 필요로 하는 유료 구독 또는 사용 크레딧이 없습니다 |1553| `free` | 계정에 빠른 모드가 필요로 하는 유료 구독 또는 사용 크레딧이 없음 |

1504| `preference` | 조직이 빠른 모드를 비활성화했습니다 |1554| `preference` | 조직이 빠른 모드를 비활성화함 |

1505| `extra_usage_disabled` | 계정에 대해 사용 크레딧이 꺼져 있습니다 |1555| `extra_usage_disabled` | 계정에 대해 사용 크레딧이 꺼짐 |

1506| `network_error` | [가용성 검사](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 도달할 수 없습니다 |1556| `network_error` | [가용성 검사](/docs/ko/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)가 `api.anthropic.com`에 도달할 수 없음 |

1507| `unknown` | Claude Code가 가용성을 결정할 수 없습니다 |1557| `unknown` | Claude Code가 가용성을 결정할 수 없음 |

1508| `not_first_party` | 세션이 Anthropic API 이외의 제공자를 사용합니다 |1558| `not_first_party` | 세션이 Anthropic API 이외의 제공자를 사용함 |

1509| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/ko/env-vars)이 설정되어 있습니다 |1559| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/ko/env-vars)이 설정됨 |

1510| `model_not_allowed` | 빠른 모드 Opus 모델이 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에 없습니다 |1560| `model_not_allowed` | 빠른 모드 Opus 모델이 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에 없음 |

1511| `sdk_opt_in_required` | 세션이 빠른 모드에 옵트인하지 않았습니다: [`settings`](#options) 옵션에서 `fastMode: true`를 전달하거나 [`applyFlagSettings()`](#applyflagsettings)를 통해 전달합니다 |1561| `sdk_opt_in_required` | 세션이 빠른 모드에 옵트인하지 않음: [`settings`](#options) 옵션 또는 [`applyFlagSettings()`](#applyflagsettings)를 통해 `fastMode: true`를 전달합니다 |

1512| `pending` | 가용성 검사가 아직 완료되지 않았습니다 |1562| `pending` | 가용성 검사가 아직 완료되지 않음 |

1513 1563 

1514동일한 필드 쌍이 [`SDKSystemMessage`](#sdksystemmessage)와 [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse)에 나타나므로 첫 번째 턴 전에 빠른 모드 상태를 읽을 수 있습니다.1564동일한 필드 쌍이 [`SDKSystemMessage`](#sdksystemmessage)와 [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse)에 나타나므로 첫 번째 턴 전에 빠른 모드 상태를 읽을 수 있습니다.

1515 1565 

1516`origin` 필드는 이 결과를 트리거한 사용자 메시지의 [`SDKMessageOrigin`](#sdkmessageorigin)을 전달합니다. SDK가 완료된 백그라운드 작업과 같은 합성 후속 턴을 주입할 때, 결과 `SDKResultMessage`는 `origin: { kind: "task-notification" }`을 전달합니다. 라우팅 또는 억제 전에 `kind`를 확인하여 프롬프트에 답하는 결과와 주입된 후속을 구분합니다.1566`origin` 필드는 이 결과를 트리거한 사용자 메시지의 [`SDKMessageOrigin`](#sdkmessageorigin)을 전달합니다. SDK가 완료된 백그라운드 작업과 같은 합성 후속 턴을 주입할 때, 결과 `SDKResultMessage`는 `origin: { kind: "task-notification" }`을 전달합니다. 트리거가 발생하고 서버 검증 메시지가 다른 세션에서 도착하는 루틴은 [작업 알림 서브종류](#task-notification-subkinds)에 설명된 `subkind`와 함께 이 종류도 도착합니다. `kind`를 확인하여 프롬프트에 답변하는 결과를 라우팅하거나 억제하기 전에 주입된 후속 작업과 구별합니다. 애플리케이션이 [예약된 실행을 선언](#declare-a-scheduled-run)하면 해당 결과도 `kind: "task-notification"`을 전달하므로 `kind`만으로 억제하지 마세요.

1567 

1568여러 백그라운드 작업 완료가 함께 대기 중일 때, Claude Code는 각각 하나의 턴이 아니라 하나의 턴에서 답변할 수 있습니다. 각 완료는 여전히 이 원점으로 자신의 결과를 생성합니다. Claude Code가 함께 답변하는 완료 중 마지막을 제외한 모든 것은 순서대로 `num_turns: 0`인 빈 결과를 생성하고, 마지막 것의 결과는 모두에 답변하는 턴을 전달합니다.

1517 1569 

1518필드는 시작 오류와 같이 사용자 턴 이전에 내보낸 결과에는 없습니다.1570필드는 시작 오류와 같이 사용자 턴 전에 내보낸 결과에는 없습니다.

1519 1571 

1520`PreToolUse` 훅이 `permissionDecision: "defer"`를 반환할 때, 결과는 `stop_reason: "tool_deferred"`를 가지며 `deferred_tool_use`는 보류 중인 도구의 `id`, `name` 및 `input`을 전달합니다. 이 필드를 읽어 요청을 자신의 UI에 표시한 다음 동일한 `session_id`로 재개하여 계속합니다. 전체 왕복은 [나중을 위해 도구 호출 연기](/docs/ko/hooks#defer-a-tool-call-for-later)를 참조하십시오.1572`PreToolUse` 훅이 `permissionDecision: "defer"`를 반환할 때, 결과는 `stop_reason: "tool_deferred"`를 가지며 `deferred_tool_use`는 보류 중인 도구의 `id`, `name`, `input`을 전달합니다. 이 필드를 읽어 자신의 UI에서 요청을 표시한 다음 동일한 `session_id`로 재개하여 계속합니다. 전체 왕복은 [나중을 위해 도구 호출 연기](/docs/ko/hooks#defer-a-tool-call-for-later)를 참조하세요.

1521 1573 

1522<h4 id="user_message_uuid">1574<h4 id="user_message_uuid">

1523 `user_message_uuid`1575 `user_message_uuid`

1524</h4>1576</h4>

1525 1577 

1526이 턴이 답한 [`SDKUserMessage`](#sdkusermessage)의 `uuid`입니다. 보낸 메시지에 대한 Claude Code의 응답을 일치시킬 수 있도록 에코됩니다. Claude Code는 메시지에 설정한 경우에만 `uuid`를 에코합니다. 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트는 없습니다.1578턴이 답변하는 [`SDKUserMessage`](#sdkusermessage)의 `uuid`로, Claude Code의 회신을 보낸 메시지와 일치시킬 수 있도록 에코됩니다. Claude Code는 메시지에 하나를 설정한 경우에만 `uuid`를 에코합니다. 필드는 `SDKUserMessage`에서 선택 사항이며, `query()`에 전달된 문자열 프롬프트는 없습니다.

1527 1579 

1528턴이 답한 메시지는 턴이 시작된 방식에 따라 달라집니다:1580턴이 답변하는 메시지는 턴이 시작된 방식에 따라 다릅니다:

1529 1581 

1530* **보낸 일반 메시지**, 즉 `isSynthetic: true` 없음: 턴은 전체 실행 동안 해당 메시지에 답합니다. 여러 메시지를 가깝게 보낼 때, Claude Code는 이를 하나의 턴으로 병합할 수 있으며, 필드는 마지막 메시지의 `uuid`만 전달합니다. 병합된 메시지 중 하나에 대한 응답을 일치시키려면 [`user_message_uuids`](#user_message_uuids)를 사용합니다.1582* **보낸 일반 메시지**, 즉 `isSynthetic: true` 없음: 턴은 전체 실행 동안 해당 메시지에 답변합니다. 여러 메시지를 가깝게 보내면 Claude Code는 이를 하나의 턴으로 병합할 수 있으며, 필드는 마지막 메시지의 `uuid`만 전달합니다. 병합된 메시지 중 하나에 회신을 일치시키려면 [`user_message_uuids`](#user_message_uuids)를 사용합니다.

1531* **`isSynthetic: true`로 보낸 메시지**: 턴은 처음에 해당 메시지에 답합니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 선택된 메시지에 답합니다. 합성 메시지의 `uuid`를 에코하려면 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 합성 턴에서 아무것도 에코하지 않습니다.1583* **`isSynthetic: true`로 보낸 메시지**: 턴은 처음에 해당 메시지에 답변합니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면 턴은 그 이후로 선택된 메시지에 답변합니다. 합성 메시지의 `uuid` 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 합성 턴에서 아무것도 에코하지 않습니다.

1532* **Claude Code가 자체 생성한 프롬프트**, 예를 들어 세션 재시작 후 중단된 작업을 계속하는 턴: 턴은 처음에 메시지에 답하지 않으며 프레임은 에코를 전달하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면, 턴은 그 이후로 해당 메시지에 답합니다. 픽업 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 이러한 턴에서 아무것도 에코하지 않습니다.1584* **Claude Code가 자체 생성한 프롬프트**, 예를 들어 세션이 재시작된 후 중단된 작업을 계속하는 턴: 턴은 처음에 메시지에 답변하지 않으며 프레임은 에코를 전달하지 않습니다. Claude Code가 도구 호출 사이에 일반 메시지를 선택하면 턴은 그 이후로 해당 메시지에 답변합니다. 픽업 에코는 Agent SDK v0.3.265 이상이 필요합니다. 이전 버전은 이러한 턴에서 아무것도 에코하지 않습니다.

1533 1585 

1534Claude Code는 세 가지 종류의 프레임에서 답한 메시지의 `uuid`를 에코합니다:1586Claude Code는 세 가지 종류의 프레임에서 답변된 메시지의 `uuid`를 에코합니다:

1535 1587 

1536* **결과**: 메시지에 답한 턴의 모든 결과입니다. Agent SDK v0.3.265 이상에서 보낸 메시지에 답한 모든 결과가 이를 전달합니다. v0.3.265 이전에는 일반 메시지가 시작한 턴의 성공 결과가 턴이 API 요청을 보내지 않았거나 연기된 도구 호출로 끝났을 때 이를 전달하지 않았습니다. v0.3.246 이전에는 오류 결과도 이를 전달하지 않았으며, v0.3.216 이전에는 모든 결과가 이를 전달하지 않았습니다.1588* **결과**: 메시지에 답변한 턴의 모든 결과입니다. Agent SDK v0.3.265 이상에서 모든 그러한 결과가 이를 전달합니다. v0.3.265 이전에는 일반 메시지가 시작한 턴의 성공 결과가 턴이 API 요청을 보내지 않았거나 연기된 도구 호출로 끝났을 때 이를 전달하지 않았습니다. v0.3.246 이전에는 오류 결과도 이를 전달하지 않았으며, v0.3.216 이전에는 모든 결과가 이를 전달하지 않았습니다.

1537* **턴의 첫 번째 응답**: 첫 번째 [어시스턴트 메시지](#sdkassistantmessage) 또는 `includePartialMessages`를 사용하면 `event.type`이 `ping`이 아닌 첫 번째 [스트림 이벤트](#sdkpartialassistantmessage)입니다. 결과가 도착하기 전에 응답을 바인드할 수 있습니다. 턴이 아무것도 스트리밍하지 않으면 Claude Code는 대신 첫 번째 어시스턴트 메시지에 설정합니다. 첫 번째 응답 에코는 Agent SDK v0.3.246 이상이 필요합니다. 턴이 답한 메시지가 턴 중간에 변경되면, 변경 후 첫 번째 응답이 필드를 전달합니다. Agent SDK v0.3.265 이상에서만 가능합니다. 이전 버전은 턴당 하나의 응답 프레임에 설정합니다.1589* **턴의 첫 번째 회신**: 첫 번째 [어시스턴트 메시지](#sdkassistantmessage) 또는 `includePartialMessages`를 사용하면 `event.type`이 `ping`이 아닌 첫 번째 [스트림 이벤트](#sdkpartialassistantmessage)로, 결과가 도착하기 전에 회신을 바인드할 수 있습니다. 턴이 아무것도 스트리밍하지 않으면 Claude Code는 대신 첫 번째 어시스턴트 메시지에 설정합니다. 첫 번째 회신 에코는 Agent SDK v0.3.246 이상이 필요합니다. 턴이 답변하는 메시지가 중간에 변경되면 변경 후 첫 번째 회신이 필드를 전달하며, Agent SDK v0.3.265 이상에서 필요합니다. 이전 버전은 턴당 하나의 회신 프레임에 설정합니다.

1538* **턴의 모든 [`thinking_tokens`](#sdkthinkingtokensmessage) 프레임**: 턴의 첫 번째 응답을 기다리지 않고 생각 진행을 보낸 메시지에 속성을 지정할 수 있습니다. Agent SDK v0.3.260 이상이 필요합니다.1590* **턴의 모든 [`thinking_tokens`](#sdkthinkingtokensmessage) 프레임**: 턴의 첫 번째 회신을 기다리지 않고 보낸 메시지에 생각 진행을 귀속시킬 수 있습니다. Agent SDK v0.3.260 이상이 필요합니다.

1539 1591 

1540Claude Code는 다음 경우에 필드를 생략합니다:1592Claude Code는 다음 경우에 필드를 생략합니다:

1541 1593 

1542* 첫 번째 응답 이외의 응답 프레임1594* 첫 번째 회신 이외의 회신 프레임

1543* 서브에이전트 프레임1595* 서브에이전트 프레임

1544* `uuid`를 가진 메시지에 답하지 않는 턴: 턴이 `uuid` 없이 보낸 메시지에 답했거나 Claude Code가 턴을 시작했으며 `uuid`를 가진 일반 메시지를 선택하지 않았습니다.1596* `uuid`가 있는 메시지에 답변하지 않는 턴: 턴이 하나 없이 보낸 메시지에 답변했거나 Claude Code가 턴을 시작했고 하나가 있는 일반 메시지를 선택하지 않았습니다

1545* 보낸 메시지에 답하지 않는 결과입니다. 예를 들어 충돌한 워커 프로세스 후 0으로 설정된 결과입니다.1597* 보낸 메시지에 답변하지 않는 결과로, 충돌한 워커 프로세스 후 0으로 설정된 결과와 같습니다

1546 1598 

1547<h4 id="user_message_uuids">1599<h4 id="user_message_uuids">

1548 `user_message_uuids`1600 `user_message_uuids`

1549</h4>1601</h4>

1550 1602 

1551이 턴에서 Claude Code가 답한 보낸 모든 메시지의 `uuid`입니다. 여러 메시지를 가깝게 보낼 때, Claude Code는 이를 하나의 턴으로 병합할 수 있으며, `user_message_uuid`는 마지막 메시지만 명명합니다. 병합된 메시지 중 하나에 대한 응답을 일치시키려면 이 목록의 어디든지 해당 메시지의 `uuid`를 찾으십시오. Agent SDK v0.3.259 이상이 필요합니다.1603Claude Code가 이 턴에서 답변한 모든 메시지의 `uuid`입니다. 여러 메시지를 가깝게 보내면 Claude Code는 이를 하나의 턴으로 병합할 수 있으며, `user_message_uuid`는 마지막 메시지만 명명합니다. 병합된 메시지 중 하나에 회신을 일치시키려면 이 목록의 어디든지 해당 메시지의 `uuid`를 찾으세요. Agent SDK v0.3.259 이상이 필요합니다.

1552 1604 

1553Claude Code는 해당 필드를 전달하는 각 응답 프레임과 결과에서 `user_message_uuid`와 함께 목록을 설정합니다. `user_message_uuid`를 전달하는 프레임의 전체 집합과 각각이 필요로 하는 버전은 [`user_message_uuid`](#user_message_uuid)를 참조하십시오. 목록은 항상 `user_message_uuid`를 포함하며 최대 64개 항목을 보유합니다.1605Claude Code는 해당 필드를 전달하는 각 회신 프레임과 결과에서 `user_message_uuid`와 함께 목록을 설정합니다. `user_message_uuid`를 전달하는 전체 프레임 세트와 각각이 필요로 하는 버전은 [`user_message_uuid`](#user_message_uuid)를 참조하세요. 목록은 항상 `user_message_uuid`를 포함하고 최대 64개 항목을 보유합니다.

1554 1606 

1555Claude Code가 턴이 실행되는 동안 보낸 일반 메시지를 선택하면, 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.1607Claude Code가 턴이 실행되는 동안 보낸 일반 메시지를 선택하면 해당 메시지의 `uuid`를 결과의 목록에 추가합니다.

1556 1608 

1557첫 번째 응답 또는 결과가 목록 없이 `user_message_uuid`를 전달하면, 이전 Claude Code 버전에서 나온 것이므로 단일 필드로 돌아갑니다.1609첫 번째 회신 또는 결과가 목록 없이 `user_message_uuid`를 전달하면 이전 Claude Code 버전에서 나온 것이므로 단일 필드로 돌아가세요.

1558 1610 

1559<h4 id="queued_turn_count">1611<h4 id="queued_turn_count">

1560 `queued_turn_count`1612 `queued_turn_count`

1562 1614 

1563Claude Code가 결과를 생성했을 때 [`origin: { kind: "human" }`](#sdkmessageorigin)으로 보낸 메시지 중 여전히 명령 큐에서 대기 중인 메시지의 수입니다. Agent SDK v0.3.242 이상이 필요합니다.1615Claude Code가 결과를 생성했을 때 [`origin: { kind: "human" }`](#sdkmessageorigin)으로 보낸 메시지 중 여전히 명령 큐에서 대기 중인 메시지의 수입니다. Agent SDK v0.3.242 이상이 필요합니다.

1564 1616 

1565`0`과 없는 필드가 무엇을 말하는지:1617`0`과 없는 필드가 무엇을 의미하는지:

1566 1618 

1567* **`0`**: Claude Code는 해당 `origin` 없이 보낸 메시지를 계산하지 않으며, 작업 알림을 계산하지 않으므로 턴이 여전히 따를 수 있습니다.1619* **`0`**: Claude Code는 해당 `origin` 없이 보낸 메시지를 계산하지 않으며, 작업 알림을 계산하지 않으므로 턴이 여전히 따를 수 있습니다.

1568* **없음**: Claude Code가 충돌 또는 치명적 시작 오류 후 내보내는 최종 결과는 필드를 생략하며, [0으로 설정된 합계를 전달할 수 있습니다](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).1620* **없음**: Claude Code가 충돌 또는 치명적 시작 오류 후 내보내는 최종 결과는 필드를 생략하며, [0으로 설정된 합계를 전달할 수 있습니다](/docs/ko/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).

1571 `startup_failure_reason`1623 `startup_failure_reason`

1572</h4>1624</h4>

1573 1625 

1574Claude Code가 시작을 거부한 이유입니다. 애플리케이션이 재시도 대신 수정을 제공할 수 있습니다. Claude Code는 알려진 시작 실패에서 종료하기 전에 작성하는 `error_during_execution` 결과에 설정합니다. 해당 결과는 0으로 설정된 합계를 전달하며, `errors` 배열은 stderr과 동일한 텍스트를 전달합니다. 필드는 다른 모든 결과에는 없습니다. Agent SDK v0.3.274 이상이 필요합니다.1626Claude Code가 시작을 거부한 이유로, 애플리케이션이 재시도 대신 수정을 제공할 수 있습니다. Claude Code는 알려진 시작 실패 전에 종료하기 전에 작성하는 `error_during_execution` 결과에 설정합니다. 해당 결과는 0으로 설정된 합계를 전달하며, 해당 `errors` 배열은 stderr와 동일한 텍스트를 전달합니다. 필드는 다른 모든 결과에는 없습니다. Agent SDK v0.3.274 이상이 필요합니다.

1575 1627 

1576모든 `SDKStartupFailureReason` 값에 대해 이 결과를 받으려면 [`env`](#options)에서 `CLAUDE_CODE_STARTUP_FAILURE_RESULTS`를 `1`로 설정합니다. 해당 변수 없이 Claude Code는 이러한 실패에 대해서만 결과를 작성하며, 나머지는 stderr 출력, 0이 아닌 종료 및 결과 메시지 없이 끝납니다:1628모든 `SDKStartupFailureReason` 값에 대해 이 결과를 받으려면 [`env`](#options)에서 `CLAUDE_CODE_STARTUP_FAILURE_RESULTS`를 `1`로 설정합니다. 해당 변수 없이 Claude Code는 이러한 실패에 대해서만 결과를 작성하고 나머지는 stderr 출력, 0이 아닌 종료, 결과 메시지 없음으로 끝납니다:

1577 1629 

1578* Claude Code가 [세션을 워크트리로 반환할 수 없기](/docs/ko/worktrees#the-session-resumes-outside-its-worktree) 때문에 중지하는 재개입니다. 해당 섹션은 어떤 오류가 어떤 값을 전달하는지 말합니다.1630* Claude Code가 [세션을 워크트리로 반환할 수 없기](/docs/ko/worktrees#the-session-resumes-outside-its-worktree) 때문에 중지하는 재개로, `worktree_unverified` 또는 `worktree_resume_refused`입니다. 해당 섹션은 어떤 오류가 어떤 값을 전달하는지 말합니다.

1579* 백그라운드 세션이 보유하는 대화의 거부된 [`continue`](#options)입니다. 그러한 대화의 거부된 [`resume`](#options)의 경우, Claude Code는 변수가 설정되었을 때만 결과를 작성합니다.1631* 백그라운드 세션이 보유하는 대화의 거부된 [`continue`](#options)로, `session_held_by_background`입니다. 그러한 대화의 거부된 [`resume`](#options)의 경우 Claude Code는 변수가 설정되었을 때만 결과를 작성합니다.

1580 1632 

1581```typescript theme={null}1633```typescript theme={null}

1582type SDKStartupFailureReason =1634type SDKStartupFailureReason =

1602 1654 

1603| 값 | 세션을 중지한 것 |1655| 값 | 세션을 중지한 것 |

1604| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |1656| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |

1605| `org_pin_api_key_conflict` | 관리 설정이 [자사 또는 Cloud 게이트웨이 로그인](/docs/ko/authentication#restrict-login-to-your-organization)을 요구하며, Anthropic API 키, 인증 토큰 또는 `apiKeyHelper`가 대신 구성되어 있습니다 |1657| `org_pin_api_key_conflict` | 관리 설정이 [첫 번째 당사자 또는 Cloud 게이트웨이 로그인](/docs/ko/authentication#restrict-login-to-your-organization)을 요구하며, Anthropic API 키, 인증 토큰 또는 `apiKeyHelper`가 대신 구성됨 |

1606| `org_verify_failed` | 로그인의 조직을 핀에 대해 확인할 수 없습니다. 예를 들어 네트워크 실패 또는 취소된 토큰 때문입니다 |1658| `org_verify_failed` | 로그인의 조직을 핀에 대해 확인할 수 없음(예: 네트워크 실패 또는 취소된 토큰) |

1607| `org_pin_mismatch` | 로그인이 핀이 허용하지 않는 조직에 속합니다 |1659| `org_pin_mismatch` | 로그인이 핀이 허용하지 않는 조직에 속함 |

1608| `managed_settings_invalid` | 관리 정책 설정을 읽을 수 없거나 핀이 조직을 명명하지 않습니다 |1660| `managed_settings_invalid` | 관리 정책 설정을 읽을 수 없거나 핀이 조직을 명명하지 않음 |

1609| `remote_settings_required_unavailable` | 조직이 요구하는 관리 설정을 로드할 수 없습니다 |1661| `remote_settings_required_unavailable` | 조직이 요구하는 관리 설정을 로드할 수 없음 |

1610| `gateway_signin_required` | [Cloud 게이트웨이](/docs/ko/claude-apps-gateway)가 이 로그인을 종료했습니다 |1662| `gateway_signin_required` | [Cloud 게이트웨이](/docs/ko/claude-apps-gateway)가 이 로그인을 종료함 |

1611| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리 설정 요청이 403으로 돌아왔습니다. 게이트웨이의 [문제 해결 테이블](/docs/ko/claude-apps-gateway-deploy#troubleshooting)이 이를 다룹니다 |1663| `gateway_access_denied` | Cloud 게이트웨이에 대한 관리 설정 요청이 403으로 돌아왔으며, 게이트웨이의 [문제 해결 테이블](/docs/ko/claude-apps-gateway-deploy#troubleshooting)이 이를 다룹니다 |

1612| `proxy_invalid` | 프록시 설정이 완전한 URL이 아닙니다 |1664| `proxy_invalid` | 프록시 설정이 완전한 URL이 아님 |

1613| `temp_dir_unusable` | 사용자별 임시 디렉토리가 안전하지 않거나 생성할 수 없습니다 |1665| `temp_dir_unusable` | 사용자별 임시 디렉토리가 안전하지 않거나 생성할 수 없음 |

1614| `cwd_unavailable` | 작업 디렉토리가 삭제되었거나 이동되었거나 읽을 수 없습니다 |1666| `cwd_unavailable` | 작업 디렉토리가 삭제되었거나 이동되었거나 읽을 수 없음 |

1615| `shell_tool_missing` | Windows에서 사용 가능한 셸 도구가 없습니다: Git Bash가 없으며 PowerShell이 없거나 `CLAUDE_CODE_USE_POWERSHELL_TOOL`로 꺼져 있습니다 |1667| `shell_tool_missing` | Windows에서 사용 가능한 셸 도구가 없음: Git Bash가 없고 PowerShell이 없거나 `CLAUDE_CODE_USE_POWERSHELL_TOOL`로 꺼짐 |

1616| `session_held_by_background` | 재개하거나 계속할 대화가 [백그라운드 세션](/docs/ko/agent-view)으로 실행 중입니다 |1668| `session_held_by_background` | 재개하거나 계속할 대화가 [백그라운드 세션](/docs/ko/agent-view)으로 실행 중 |

1617| `worktree_resume_refused` | 세션의 워크트리가 안전 검사에 실패했거나 재개가 내부에서 시작되었습니다. `errors`는 동일한 재개를 다시 실행하면 워크트리 없이 계속되는지 말합니다 |1669| `worktree_resume_refused` | 세션의 워크트리가 안전 검사에 실패했거나 재개가 내부에서 시작됨. `errors`는 동일한 재개를 다시 실행하면 워크트리 없이 계속되는지 여부를 말합니다 |

1618| `worktree_unverified` | 세션의 워크트리를 지금 확인할 수 없으며, 재시도하면 성공할 수 있습니다 |1670| `worktree_unverified` | 세션의 워크트리를 지금 확인할 수 없으며 재시도하면 성공할 수 있음 |

1619| `cli_version_too_old` | 이 Claude Code 버전이 Anthropic이 요구하는 최소값 아래입니다 |1671| `cli_version_too_old` | 이 Claude Code 버전이 Anthropic이 요구하는 최소값 아래 |

1620| `bypass_root` | 루트로 실행하는 동안 바이패스 권한 모드가 요청되었습니다 |1672| `bypass_root` | 루트로 실행하는 동안 바이패스 권한 모드가 요청됨 |

1621 1673 

1622<h3 id="sdksystemmessage">1674<h3 id="sdksystemmessage">

1623 `SDKSystemMessage`1675 `SDKSystemMessage`

1656};1708};

1657```1709```

1658 1710 

1659`fast_mode_state`는 세션의 [빠른 모드](/docs/ko/fast-mode) 상태를 보고합니다. 빠른 모드를 차단하는 것이 있으면, `fast_mode_disabled_reason`은 이를 차단한 검사의 이름을 지정합니다. 필드는 Claude Code v2.1.219 이상이 필요합니다. 이유 코드 및 의미는 결과 메시지의 [`fast_mode_disabled_reason`](#sdkresultmessage)을 참조하십시오.1711`fast_mode_state`는 세션의 [빠른 모드](/docs/ko/fast-mode) 상태를 보고합니다. 무언가가 빠른 모드를 차단할 때 `fast_mode_disabled_reason`은 이를 차단한 검사의 이름을 지정합니다. 필드는 Claude Code v2.1.219 이상이 필요합니다. 이유 코드와 그 의미는 결과 메시지의 [`fast_mode_disabled_reason`](#sdkresultmessage)을 참조하세요.

1660 1712 

1661`terminal_slash_commands`는 `slash_commands`의 항목 중 인터페이스가 로컬 터미널에 바인드된 항목의 이름을 지정합니다. 예를 들어 `exit`입니다. 다른 `slash_commands` 항목처럼 보낼 수 있습니다. 필드는 원격 또는 모바일 클라이언트가 명령 메뉴에서 이를 숨길 수 있도록 존재합니다. 필드는 비어 있지 않을 때만 표시되며 Agent SDK v0.3.229 이상이 필요합니다.1713`terminal_slash_commands`는 `exit`와 같은 로컬 터미널에 바인드된 인터페이스를 가진 `slash_commands`의 항목을 명명합니다. 다른 `slash_commands` 항목처럼 보낼 수 있습니다. 필드는 원격 또는 모바일 클라이언트가 명령 메뉴에서 이를 숨길 수 있도록 존재합니다. 필드는 비어 있지 않을 때만 있으며 Agent SDK v0.3.229 이상이 필요합니다.

1662 1714 

1663* 각 `mcp_servers` 항목의 `source`: 서버 정의가 어디에서 나왔는지입니다. [`McpServerStatus`](#mcpserverstatus)의 `source`와 동일한 값입니다. Agent SDK v0.3.274 이상이 필요합니다.1715* 각 `mcp_servers` 항목의 `source`: 서버 정의가 어디에서 나왔는지로, [`McpServerStatus`](#mcpserverstatus)의 `source`와 동일한 값입니다. Agent SDK v0.3.274 이상이 필요합니다.

1664* `effort`: [노력 수준](/docs/ko/model-config#adjust-effort-level) Claude Code가 세션의 다음 요청에서 보내거나, 보내지 않을 때 `null`입니다. Claude Code는 [Remote Control](/docs/ko/remote-control) 클라이언트에 보내는 초기화 메시지에만 필드를 설정하며, 애플리케이션이 읽는 초기화 메시지에서 생략합니다. Agent SDK v0.3.234 이상이 필요합니다.1716* `effort`: [노력 수준](/docs/ko/model-config#adjust-effort-level) Claude Code가 세션의 다음 요청에서 보내거나 보내지 않을 때 `null`입니다. Claude Code는 [Remote Control](/docs/ko/remote-control) 클라이언트로 보내는 초기화 메시지에만 필드를 설정하고 애플리케이션이 읽는 초기화 메시지에서 생략합니다. Agent SDK v0.3.234 이상이 필요합니다.

1665 1717 

1666`capabilities` 배열은 이 CLI가 구현하는 프로토콜 동작의 이름을 지정하므로 `claude_code_version` 문자열을 비교하는 대신 기능을 감지할 수 있습니다. 이는 개방형 집합입니다: 인식하지 못하는 값은 무시하고 의존하는 동작의 특정 기능을 확인합니다. 필드는 Claude Code v2.1.205 이상이 필요하며 이전 CLI에는 없습니다.1718`capabilities` 배열은 이 CLI가 구현하는 프로토콜 동작의 이름을 지정하므로 `claude_code_version` 문자열을 비교하는 대신 기능을 감지할 수 있습니다. 이는 열린 집합입니다: 인식하지 못하는 값을 무시하고 동작이 의존하는 특정 기능을 확인합니다. 필드는 Claude Code v2.1.205 이상이 필요하며 이전 CLI에는 없습니다.

1667 1719 

1668| 기능 | 의미 |1720| 기능 | 의미 |

1669| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1721| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1670| `interrupt_receipt_v1` | [`interrupt()`](#query-object)는 중단을 생존하는 대기 중인 메시지의 이름을 지정하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 영수증으로 해결됩니다 |1722| `interrupt_receipt_v1` | [`interrupt()`](#query-object)는 인터럽트가 도착했을 때 보류 중인 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 영수증으로 해결됩니다 |

1671| `interrupt_cancel_queued_v1` | 중단 제어 요청이 `cancel_queued: true`를 준수하여 영수증이 `still_queued` 아래에 나열할 메시지를 취소하고 대신 `cancelled` 아래에 나열합니다. [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)를 참조하십시오. Claude Code v2.1.219 이상이 필요합니다 |1723| `interrupt_cancel_queued_v1` | `interrupt` 제어 요청이 `cancel_queued: true`를 준수하여 영수증이 `still_queued` 아래에 나열할 메시지를 취소하고 대신 `cancelled` 아래에 나열합니다. [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)를 참조하세요. Claude Code v2.1.219 이상이 필요합니다 |

1672 1724 

1673<h3 id="sdkpartialassistantmessage">1725<h3 id="sdkpartialassistantmessage">

1674 `SDKPartialAssistantMessage`1726 `SDKPartialAssistantMessage`

1675</h3>1727</h3>

1676 1728 

1677스트리밍 부분 메시지 (`includePartialMessages`가 true일 때만). `parent_tool_use_id` 필드는 항상 `null`입니다: 스트림 이벤트는 메인 세션에만 내보내집니다. 서브에이전트 속성을 위해 `parent_tool_use_id`를 전달하는 완전한 메시지를 사용하거나 [`forwardSubagentText`](#options)를 활성화하여 서브에이전트 텍스트와 생각을 완전한 메시지로 수신합니다.1729스트리밍 부분 메시지(`includePartialMessages`가 true일 때만). `parent_tool_use_id` 필드는 항상 `null`입니다: 스트림 이벤트는 메인 세션에만 내보내집니다. 서브에이전트 귀속의 경우 완전한 메시지를 사용하거나 [`forwardSubagentText`](#options)를 활성화하여 서브에이전트 텍스트 및 생각을 완전한 메시지로 받습니다.

1678 1730 

1679```typescript theme={null}1731```typescript theme={null}

1680type SDKPartialAssistantMessage = {1732type SDKPartialAssistantMessage = {

1681 type: "stream_event";1733 type: "stream_event";

1682 event: BetaRawMessageStreamEvent; // Anthropic SDK에서1734 event: BetaRawMessageStreamEvent; // From Anthropic SDK

1683 parent_tool_use_id: string | null;1735 parent_tool_use_id: string | null;

1684 uuid: UUID;1736 uuid: UUID;

1685 session_id: string;1737 session_id: string;

1686 ttft_ms?: number; // 첫 번째 토큰까지의 시간(ms), message_start 이벤트에만 표시됨1738 ttft_ms?: number; // Time to first token in ms, present only on message_start events

1687 user_message_uuid?: string;1739 user_message_uuid?: string;

1688 user_message_uuids?: string[];1740 user_message_uuids?: string[];

1689};1741};

1690```1742```

1691 1743 

1692Claude Code는 턴의 첫 번째 비핑 스트림 이벤트에 `user_message_uuid` 및 `user_message_uuids`를 설정하며, 턴이 답한 메시지가 변경될 때 다시 설정합니다. [`user_message_uuid`](#user_message_uuid)의 조건에 따릅니다.1744Claude Code는 턴의 첫 번째 비핑 스트림 이벤트에 `user_message_uuid`와 `user_message_uuids`를 설정하고, 턴이 답변하는 메시지가 변경될 때 [`user_message_uuid`](#user_message_uuid)의 조건에 따라 다시 설정합니다.

1693 1745 

1694<h3 id="sdkcompactboundarymessage">1746<h3 id="sdkcompactboundarymessage">

1695 `SDKCompactBoundaryMessage`1747 `SDKCompactBoundaryMessage`

1714 `SDKInformationalMessage`1766 `SDKInformationalMessage`

1715</h3>1767</h3>

1716 1768 

1717루프에서 내보낸 일반 텍스트 배너입니다. 비오류 상태 라인, `UserPromptSubmit` 훅의 블록 이유와 같은 훅 피드백, 및 명령 출력을 전달합니다. Claude Code v2.1.227 이상에서 훅의 [`systemMessage`](/docs/ko/hooks#json-output)는 이 메시지로 도착할 수 있으며, 각 줄은 훅의 이름으로 접두사가 붙습니다. 예를 들어 `PostToolUse:Bash says:`입니다. 훅의 `systemMessage`가 이 메시지로 도착하는지 여부는 이벤트에 따라 달라집니다. 각 [이벤트의 섹션](/docs/ko/hooks#hook-events)은 훅 페이지에서 출력이 어떻게 표시되는지 말합니다. `content`를 주어진 `level`에서 일반 텍스트로 렌더링합니다.1769루프에서 내보낸 일반 텍스트 배너입니다. 비오류 상태 줄, `UserPromptSubmit` 훅의 블록 이유와 같은 훅 피드백, 명령 출력을 전달합니다. Claude Code v2.1.227 이상에서 훅의 [`systemMessage`](/docs/ko/hooks#json-output)는 이 메시지로 도착할 수 있으며, 각 줄은 `PostToolUse:Bash says:`와 같은 훅의 이름으로 접두사가 붙습니다. 훅의 `systemMessage`가 이 메시지로 도착하는지 여부는 이벤트에 따라 다릅니다. 각 [이벤트의 섹션](/docs/ko/hooks#hook-events)은 훅 페이지에서 출력이 어떻게 표시되는지 말합니다. `content`를 주어진 `level`에서 일반 텍스트로 렌더링합니다.

1718 1770 

1719```typescript theme={null}1771```typescript theme={null}

1720type SDKInformationalMessage = {1772type SDKInformationalMessage = {

1733 `SDKWorkerShuttingDownMessage`1785 `SDKWorkerShuttingDownMessage`

1734</h3>1786</h3>

1735 1787 

1736원격 클라이언트가 하트비트 타임아웃을 기다리는 대신 워커가 사라진 이유를 표시할 수 있도록 정상적인 워커 종료 시 내보내집니다. `reason`은 호스트 CLI에서 설정한 짧은 snake\_case 문자열입니다(예: `"host_exit"` 또는 `"remote_control_disabled"`). 라이브 스트리밍할 때만 이에 대해 조치합니다. 재개된 세션은 이 메시지의 과거 인스턴스를 재생하므로 그 경우 무시합니다.1788정상적인 워커 해제 시 내보내져서 원격 클라이언트가 하트비트 타임아웃을 기다리는 대신 워커가 종료된 이유를 표시할 수 있습니다. `reason`은 호스트 CLI에서 설정한 짧은 snake\_case 문자열로, `"host_exit"` 또는 `"remote_control_disabled"`와 같습니다. 라이브 스트리밍할 때만 이에 대해 조치합니다. 재개된 세션은 이 메시지의 과거 인스턴스를 재생하므로 그 경우 무시합니다.

1737 1789 

1738```typescript theme={null}1790```typescript theme={null}

1739type SDKWorkerShuttingDownMessage = {1791type SDKWorkerShuttingDownMessage = {

1749 `SDKPluginInstallMessage`1801 `SDKPluginInstallMessage`

1750</h3>1802</h3>

1751 1803 

1752플러그인 설치 진행 이벤트입니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/ko/env-vars)이 설정되면 내보내지므로 Agent SDK 애플리케이션이 첫 번째 턴 전에 마켓플레이스 플러그인 설치를 추적할 수 있습니다. `started` 및 `completed` 상태는 전체 설치를 괄호로 묶습니다. `installed` 및 `failed` 상태는 개별 마켓플레이스를 보고하고 `name`을 포함합니다.1804플러그인 설치 진행 이벤트입니다. [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/ko/env-vars)이 설정되었을 때 내보내져서 Agent SDK 애플리케이션이 첫 번째 턴 전에 마켓플레이스 플러그인 설치를 추적할 수 있습니다. `started`와 `completed` 상태는 전체 설치를 괄호로 묶습니다. `installed`와 `failed` 상태는 개별 마켓플레이스를 보고하고 `name`을 포함합니다.

1753 1805 

1754```typescript theme={null}1806```typescript theme={null}

1755type SDKPluginInstallMessage = {1807type SDKPluginInstallMessage = {

1767 `SDKPermissionDeniedMessage`1819 `SDKPermissionDeniedMessage`

1768</h3>1820</h3>

1769 1821 

1770권한 시스템이 대화형 프롬프트 없이 도구 호출을 자동으로 거부할 때 내보내지는 스트림 이벤트입니다. 이를 사용하여 거부를 UI에 렌더링할 수 있습니다. 어떤 거부를 보고하는지는 실행이 권한 프롬프트를 처리하는 방식에 따라 달라집니다:1822권한 시스템이 대화형 프롬프트 없이 도구 호출을 거부할 때 내보낸 스트림 이벤트입니다. 뒤따르는 `is_error` 도구 결과만 관찰하는 대신 거부를 실시간으로 UI에 렌더링하는 데 사용합니다. 어떤 거부를 보고하는지는 실행이 권한 프롬프트를 처리하는 방식에 따라 다릅니다:

1771 1823 

1772* **[`canUseTool`](#canusetool) 콜백과 기본 [`permissionPrompts: 'host'`](#options)**: 권한 프롬프트는 콜백으로 이동하며, 이 이벤트는 Claude Code가 이를 호출하지 않고 자체적으로 결정한 거부를 보고합니다.1824* **[`canUseTool`](#canusetool) 콜백과 기본 [`permissionPrompts: 'host'`](#options)**: 권한 프롬프트는 콜백으로 이동하고, 이 이벤트는 Claude Code가 이를 호출하지 않고 자체적으로 결정한 거부를 보고합니다.

1773* **둘 다 없음**: 베어 `-p` 실행 또는 `canUseTool` 또는 `permissionPromptToolName`을 설정하지 않는 `query()`는 프롬프트했을 도구 호출을 거부하며, 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. v2.1.223 이전에는 Claude Code가 콜백 없는 실행에서 이 이벤트를 내보내지 않았습니다.1825* **둘 다 없음**: 베어 `-p` 실행 또는 `canUseTool`도 `permissionPromptToolName`도 설정하지 않는 `query()`는 프롬프트했을 모든 도구 호출을 거부하고, 이 이벤트는 그러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. v2.1.223 이전에는 Claude Code가 콜백 없는 실행에서 이 이벤트를 내보내지 않았습니다.

1774* **MCP 프롬프트 도구**, `permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정되고 기본 `permissionPrompts: 'host'`: Claude Code는 이 이벤트를 전혀 내보내지 않습니다. 자체적으로 결정한 규칙 거부도 아닙니다.1826* **MCP 프롬프트 도구**, `permissionPromptToolName` 또는 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 플래그로 설정하고 기본 `permissionPrompts: 'host'`: Claude Code는 이 이벤트를 전혀 내보내지 않으며, 규칙 거부를 포함하여 자체적으로 결정한 거부도 포함하지 않습니다.

1775* **[`permissionPrompts: 'none'`](#options)**: Claude Code는 프롬프트했을 호출을 거부합니다. `canUseTool` 또는 MCP 프롬프트 도구도 설정되어 있어도 마찬가지입니다. 이 이벤트는 이러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. Claude Code v2.1.259 이상이 필요합니다.1827* **[`permissionPrompts: 'none'`](#options)**: Claude Code는 프롬프트했을 호출을 거부하며, `canUseTool` 또는 MCP 프롬프트 도구도 설정되어 있을 때도 거부하고, 이 이벤트는 그러한 거부와 Claude Code가 자체적으로 결정한 거부를 보고합니다. Claude Code v2.1.259 이상이 필요합니다.

1776 1828 

1777모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정한 거부를 건너뜁니다. 훅이 호출을 자체적으로 거부했거나 거부 규칙이 훅의 허용 또는 요청 결정을 재정의했는지 여부입니다. 이벤트는 또한 최선의 노력입니다: 가끔 Claude Code는 이 이벤트를 내보내지 않고 거부를 기록하므로 [결과 메시지](#sdkresultmessage)의 `permission_denials`이 권위 있는 기록입니다.1829모든 구성에서 이 이벤트는 `PreToolUse` 훅 경로에서 결정된 거부를 건너뜁니다. 훅이 호출을 거부했는지 또는 거부 규칙이 훅의 허용 또는 요청 결정을 재정의했는지 여부입니다. 이벤트는 또한 최선의 노력입니다: 때때로 Claude Code는 이 이벤트를 내보내지 않고 거부를 기록하므로 [결과 메시지](#sdkresultmessage)의 `permission_denials`이 권위 있는 기록입니다.

1778 1830 

1779```typescript theme={null}1831```typescript theme={null}

1780type SDKPermissionDeniedMessage = {1832type SDKPermissionDeniedMessage = {

1794| 필드 | 타입 | 설명 |1846| 필드 | 타입 | 설명 |

1795| ---------------------- | -------- | --------------------------------------------------------------------------------- |1847| ---------------------- | -------- | --------------------------------------------------------------------------------- |

1796| `tool_name` | `string` | 거부된 도구의 이름 |1848| `tool_name` | `string` | 거부된 도구의 이름 |

1797| `tool_use_id` | `string` | 이 거부가 답하는 `tool_use` 블록의 ID |1849| `tool_use_id` | `string` | 이 거부가 답변하는 `tool_use` 블록의 ID |

1798| `agent_id` | `string` | 거부된 호출이 서브에이전트 내부에서 발생한 경우 서브에이전트 ID입니다. 호스트 측 라우팅을 위해 `can_use_tool`의 필드를 미러링합니다 |1850| `agent_id` | `string` | 거부된 호출이 서브에이전트 내부에서 발생했을 때 서브에이전트 ID입니다. 호스트 측 라우팅을 위해 `can_use_tool`의 필드를 미러링합니다 |

1799| `decision_reason_type` | `string` | `"rule"`, `"mode"`, `"classifier"` 또는 `"asyncAgent"`와 같이 결정한 구성 요소의 판별자 |1851| `decision_reason_type` | `string` | 결정한 구성 요소의 판별자로, `"rule"`, `"mode"`, `"classifier"`, 또는 `"asyncAgent"`와 같습니다 |

1800| `decision_reason` | `string` | 사용 가능할 때 결정 구성 요소의 인간이 읽을 수 있는 이유 |1852| `decision_reason` | `string` | 사용 가능할 때 결정 구성 요소의 인간이 읽을 수 있는 이유 |

1801| `message` | `string` | `tool_result`에서 모델에 반환된 거부 메시지 |1853| `message` | `string` | `tool_result`에서 모델로 반환된 거부 메시지 |

1802 1854 

1803<h3 id="sdkpermissiondenial">1855<h3 id="sdkpermissiondenial">

1804 `SDKPermissionDenial`1856 `SDKPermissionDenial`

1818 `SDKContextUsage`1870 `SDKContextUsage`

1819</h3>1871</h3>

1820 1872