Documentation 2026-08-03 20:02 UTC to 2026-08-04 22:59 UTC

22 22 

23* 한 세션의 경우: `claude --ax-screen-reader`를 실행합니다.23* 한 세션의 경우: `claude --ax-screen-reader`를 실행합니다.

24* 한 셸에서 시작된 세션의 경우: `CLAUDE_AX_SCREEN_READER` 환경 변수를 `1`로 설정합니다. Bash 또는 Zsh에서는 `export CLAUDE_AX_SCREEN_READER=1`을 실행하고, PowerShell에서는 `$env:CLAUDE_AX_SCREEN_READER = "1"`을 실행합니다. 모든 셸을 포함하려면 셸 프로필에 줄을 추가합니다.24* 한 셸에서 시작된 세션의 경우: `CLAUDE_AX_SCREEN_READER` 환경 변수를 `1`로 설정합니다. Bash 또는 Zsh에서는 `export CLAUDE_AX_SCREEN_READER=1`을 실행하고, PowerShell에서는 `$env:CLAUDE_AX_SCREEN_READER = "1"`을 실행합니다. 모든 셸을 포함하려면 셸 프로필에 줄을 추가합니다.

25* 머신의 모든 세션의 경우: 사용자 [설정 파일](/ko/settings)에 `"axScreenReader": true`를 추가합니다. 이는 VS Code 통합 터미널을 포함한 모든 터미널을 포함합니다.25* 머신의 모든 세션의 경우: 사용자 [설정 파일](/docs/ko/settings)에 `"axScreenReader": true`를 추가합니다. 이는 VS Code 통합 터미널을 포함한 모든 터미널을 포함합니다.

26 26 

27<Note>27<Note>

28 메서드는 우선순위 순서로 나열됩니다: [`--ax-screen-reader`](/ko/cli-reference#cli-flags) 플래그는 [`CLAUDE_AX_SCREEN_READER`](/ko/env-vars) 환경 변수를 재정의하고, 이는 [`axScreenReader`](/ko/settings#available-settings) 설정을 재정의합니다.28 메서드는 우선순위 순서로 나열됩니다: [`--ax-screen-reader`](/docs/ko/cli-reference#cli-flags) 플래그는 [`CLAUDE_AX_SCREEN_READER`](/docs/ko/env-vars) 환경 변수를 재정의하고, 이는 [`axScreenReader`](/docs/ko/settings#available-settings) 설정을 재정의합니다.

29</Note>29</Note>

30 30 

31SSH를 통해 Claude Code를 사용하는 경우 Claude Code가 실행되는 원격 머신에서 환경 변수 또는 설정을 설정합니다.31SSH를 통해 Claude Code를 사용하는 경우 Claude Code가 실행되는 원격 머신에서 환경 변수 또는 설정을 설정합니다.

32 32 

33모드가 켜져 있으면 Claude Code가 인쇄하는 첫 번째 것은 모드를 켠 메서드의 이름을 지정하는 확인 줄입니다: `[Screen Reader Mode: on via flag]`, `[Screen Reader Mode: on via env]` 또는 `[Screen Reader Mode: on via settings]`. 메서드 명명 형식은 Claude Code v2.1.206 이상이 필요합니다. Claude Code가 예를 들어 업데이트 설치를 완료하기 위해 자신을 다시 시작할 때 새 프로세스는 `CLAUDE_AX_SCREEN_READER` 환경 변수를 통해 모드를 상속하므로 사용한 메서드와 관계없이 확인 줄은 `[Screen Reader Mode: on via env]`로 읽힙니다.33모드가 켜져 있으면 Claude Code가 인쇄하는 첫 번째 것은 모드를 켠 메서드의 이름을 지정하는 확인 줄입니다: `[Screen Reader Mode: on via flag]`, `[Screen Reader Mode: on via env]` 또는 `[Screen Reader Mode: on via settings]`. 메서드 명명 형식은 Claude Code v2.1.206 이상이 필요합니다. Claude Code가 예를 들어 업데이트 설치를 완료하기 위해 자신을 다시 시작할 때 새 프로세스는 `CLAUDE_AX_SCREEN_READER` 환경 변수를 통해 모드를 상속하므로 사용한 메서드와 관계없이 확인 줄은 `[Screen Reader Mode: on via env]`로 읽힙니다.

34{/* max-version: 2.1.205 */}이전 버전은 `[Accessible screen reader mode: on]`을 인쇄합니다.34이전 버전은 `[Accessible screen reader mode: on]`을 인쇄합니다.

35 35 

36<h2 id="turn-off-screen-reader-mode">36<h2 id="turn-off-screen-reader-mode">

37 스크린 리더 모드 끄기37 스크린 리더 모드 끄기

48* 인터페이스 크롬에 대한 상자 그리기 문자 없음48* 인터페이스 크롬에 대한 상자 그리기 문자 없음

49* 색상 전용 신호 없음49* 색상 전용 신호 없음

50* 변경되지 않은 콘텐츠의 다시 그리기 없음; 진행 스피너는 정적 텍스트로 렌더링됨50* 변경되지 않은 콘텐츠의 다시 그리기 없음; 진행 스피너는 정적 텍스트로 렌더링됨

51* Claude의 회신의 표는 상자 문자 그리드 대신 `Header: value` 문장으로 읽힙니다. {/* min-version: 2.1.198 */}Claude Code v2.1.198 이상이 필요합니다; 이전 버전은 스크린 리더 모드에서도 표를 그리드로 그립니다.51* Claude의 회신의 표는 상자 문자 그리드 대신 `Header: value` 문장으로 읽힙니다. Claude Code v2.1.198 이상이 필요합니다; 이전 버전은 스크린 리더 모드에서도 표를 그리드로 그립니다.

52 52 

53출력은 터미널의 스크롤백에 누적되므로 스크린 리더의 검토 명령 또는 터미널의 검색을 사용하여 이전 턴을 다시 읽을 수 있습니다.53출력은 터미널의 스크롤백에 누적되므로 스크린 리더의 검토 명령 또는 터미널의 검색을 사용하여 이전 턴을 다시 읽을 수 있습니다.

54 54 

55스크린 리더 모드는 [`tui` 설정](/ko/settings#available-settings)으로 [전체 화면 렌더링](/ko/fullscreen)을 켜도 평문 스크롤로 렌더링됩니다; 모드가 활성화되어 있는 동안 설정은 효과가 없습니다. 첨부된 백그라운드 세션은 여전히 전체 화면으로 렌더링됩니다; [알려진 제한 사항](#known-limitations)을 참조하십시오.55스크린 리더 모드는 [`tui` 설정](/docs/ko/settings#available-settings)으로 [전체 화면 렌더링](/docs/ko/fullscreen)을 켜도 평문 스크롤로 렌더링됩니다; 모드가 활성화되어 있는 동안 설정은 효과가 없습니다. 첨부된 백그라운드 세션은 여전히 전체 화면으로 렌더링됩니다; [알려진 제한 사항](#known-limitations)을 참조하십시오.

56 56 

57트랜스크립트의 각 메시지는 스크린 리더가 발표하는 레이블로 시작하며, 메시지가 무엇인지 이름을 지정합니다: 사용자 메시지, Claude의 회신, 도구 활동, 오류 및 프롬프트. 레이블은 검색 가능하므로 터미널의 스크롤백을 검색하여 트랜스크립트의 섹션 간에 이동할 수 있습니다:57트랜스크립트의 각 메시지는 스크린 리더가 발표하는 레이블로 시작하며, 메시지가 무엇인지 이름을 지정합니다: 사용자 메시지, Claude의 회신, 도구 활동, 오류 및 프롬프트. 레이블은 검색 가능하므로 터미널의 스크롤백을 검색하여 트랜스크립트의 섹션 간에 이동할 수 있습니다:

58 58 

64| `tool error:` | 실패한 도구 |64| `tool error:` | 실패한 도구 |

65| `error:` | 실패한 API 요청과 같은 대화의 오류 |65| `error:` | 실패한 API 요청과 같은 대화의 오류 |

66| `Permission Required:` | 사용자의 답변을 기다리는 권한 프롬프트 |66| `Permission Required:` | 사용자의 답변을 기다리는 권한 프롬프트 |

67| `Cost:` | Claude Code가 종료될 때 세션 비용 요약(계정이 [비용을 표시](/ko/costs)하는 경우) |67| `Cost:` | Claude Code가 종료될 때 세션 비용 요약(계정이 [비용을 표시](/docs/ko/costs)하는 경우) |

68 68 

69터미널 커서는 입력 캐럿을 따르므로 스크린 리더의 현재 줄 읽기 명령은 편집 중인 프롬프트로 "내가 어디에 있는가"에 답합니다.69터미널 커서는 입력 캐럿을 따르므로 스크린 리더의 현재 줄 읽기 명령은 편집 중인 프롬프트로 "내가 어디에 있는가"에 답합니다.

70 70 

102* 권한 프롬프트가 나타납니다102* 권한 프롬프트가 나타납니다

103* 5초 이상 실행된 도구가 완료됩니다103* 5초 이상 실행된 도구가 완료됩니다

104 104 

105벨은 터미널의 표준 경고입니다. 벨을 끄려면 터미널 애플리케이션에서 벨 설정을 변경합니다. 벨은 스크린 리더 모드를 요구하지 않습니다: 모드 외부에서 [`preferredNotifChannel`](/ko/settings#available-settings)을 `"terminal_bell"`로 설정하여 Claude가 사용자를 기다릴 때 유사한 경고를 받습니다. [터미널 벨 또는 알림 받기](/ko/terminal-config#get-a-terminal-bell-or-notification)를 참조하십시오.105벨은 터미널의 표준 경고입니다. 벨을 끄려면 터미널 애플리케이션에서 벨 설정을 변경합니다. 벨은 스크린 리더 모드를 요구하지 않습니다: 모드 외부에서 [`preferredNotifChannel`](/docs/ko/settings#available-settings)을 `"terminal_bell"`로 설정하여 Claude가 사용자를 기다릴 때 유사한 경고를 받습니다. [터미널 벨 또는 알림 받기](/docs/ko/terminal-config#get-a-terminal-bell-or-notification)를 참조하십시오.

106 106 

107<h2 id="accessibility-settings-beyond-screen-reader-mode">107<h2 id="accessibility-settings-beyond-screen-reader-mode">

108 스크린 리더 모드 이외의 접근성 설정108 스크린 리더 모드 이외의 접근성 설정

110 110 

111이러한 옵션은 스크린 리더 모드 외부의 접근성 요구 사항을 해결합니다. 모두 함께 작동합니다.111이러한 옵션은 스크린 리더 모드 외부의 접근성 요구 사항을 해결합니다. 모두 함께 작동합니다.

112 112 

113* `CLAUDE_CODE_ACCESSIBILITY` [환경 변수](/ko/env-vars)는 스크린 확대기용입니다. `CLAUDE_CODE_ACCESSIBILITY=1`을 설정하여 macOS Zoom과 같은 확대기가 커서 위치를 추적할 수 있도록 기본 터미널 커서를 표시합니다.113* `CLAUDE_CODE_ACCESSIBILITY` [환경 변수](/docs/ko/env-vars)는 스크린 확대기용입니다. `CLAUDE_CODE_ACCESSIBILITY=1`을 설정하여 macOS Zoom과 같은 확대기가 커서 위치를 추적할 수 있도록 기본 터미널 커서를 표시합니다.

114* `prefersReducedMotion` [설정](/ko/settings#available-settings)은 인터페이스의 나머지를 변경하지 않고 스피너, 반짝임 및 기타 애니메이션을 줄이거나 비활성화합니다.114* `prefersReducedMotion` [설정](/docs/ko/settings#available-settings)은 인터페이스의 나머지를 변경하지 않고 스피너, 반짝임 및 기타 애니메이션을 줄이거나 비활성화합니다.

115* `theme` [설정](/ko/settings#available-settings)은 색맹 친화적 `dark-daltonized` 및 `light-daltonized` 테마를 포함한 인터페이스 색상을 선택합니다.115* `theme` [설정](/docs/ko/settings#available-settings)은 색맹 친화적 `dark-daltonized` 및 `light-daltonized` 테마를 포함한 인터페이스 색상을 선택합니다.

116 116 

117<h2 id="known-limitations">117<h2 id="known-limitations">

118 알려진 제한 사항118 알려진 제한 사항

121일부 동작은 스크린 리더 모드에 맞게 조정되지 않습니다:121일부 동작은 스크린 리더 모드에 맞게 조정되지 않습니다:

122 122 

123* 스크린 리더 모드는 스크린 리더가 실행 중일 때 자동으로 켜지지 않습니다.123* 스크린 리더 모드는 스크린 리더가 실행 중일 때 자동으로 켜지지 않습니다.

124* [계획 모드](/ko/permission-modes#analyze-before-you-edit-with-plan-mode) 진입과 같은 모드 변경은 아직 발표되지 않습니다.124* [계획 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode) 진입과 같은 모드 변경은 아직 발표되지 않습니다.

125* `claude attach` 또는 에이전트 보기에서 [백그라운드 세션](/ko/agent-view)에 첨부하면 기본 스크롤백이 없는 터미널의 대체 화면으로 들어갑니다. 이는 [다른 첨부된 세션과 동일한 동작](/ko/fullscreen)입니다. 나가려면 빈 프롬프트에서 왼쪽 화살표를 누르거나 대화 상자에 포커스가 있으면 Ctrl+Z를 누릅니다.125* `claude attach` 또는 에이전트 보기에서 [백그라운드 세션](/docs/ko/agent-view)에 첨부하면 기본 스크롤백이 없는 터미널의 대체 화면으로 들어갑니다. 이는 [다른 첨부된 세션과 동일한 동작](/docs/ko/fullscreen)입니다. 나가려면 빈 프롬프트에서 왼쪽 화살표를 누르거나 대화 상자에 포커스가 있으면 Ctrl+Z를 누릅니다.

126* Claude Code는 종료 시 인쇄하는 요약에서 비용을 발표하며, 턴당이 아닙니다.126* Claude Code는 종료 시 인쇄하는 요약에서 비용을 발표하며, 턴당이 아닙니다.

127* 스크린 리더 모드는 `-p` 플래그로 [비대화형 모드](/ko/headless)를 변경하지 않습니다. 비대화형 모드는 이미 평문을 작성하며 스크립팅을 위한 대안으로 남아 있습니다.127* 스크린 리더 모드는 `-p` 플래그로 [비대화형 모드](/docs/ko/headless)를 변경하지 않습니다. 비대화형 모드는 이미 평문을 작성하며 스크립팅을 위한 대안으로 남아 있습니다.

128 128 

129<h2 id="report-an-issue">129<h2 id="report-an-issue">

130 문제 보고130 문제 보고

138 138 

139이 페이지는 이 페이지에서 다루는 내용에 대한 전체 참조 항목 및 관련 설정을 보유합니다:139이 페이지는 이 페이지에서 다루는 내용에 대한 전체 참조 항목 및 관련 설정을 보유합니다:

140 140 

141* [설정](/ko/settings#available-settings): `axScreenReader`, `prefersReducedMotion`, `theme` 및 `preferredNotifChannel` 항목141* [설정](/docs/ko/settings#available-settings): `axScreenReader`, `prefersReducedMotion`, `theme` 및 `preferredNotifChannel` 항목

142* [환경 변수](/ko/env-vars): `CLAUDE_AX_SCREEN_READER` 및 `CLAUDE_CODE_ACCESSIBILITY` 항목142* [환경 변수](/docs/ko/env-vars): `CLAUDE_AX_SCREEN_READER` 및 `CLAUDE_CODE_ACCESSIBILITY` 항목

143* [CLI 참조](/ko/cli-reference#cli-flags): `--ax-screen-reader` 플래그143* [CLI 참조](/docs/ko/cli-reference#cli-flags): `--ax-screen-reader` 플래그

144* [터미널 구성](/ko/terminal-config): 스크린 리더 모드 외부의 벨, 알림 및 테마144* [터미널 구성](/docs/ko/terminal-config): 스크린 리더 모드 외부의 벨, 알림 및 테마

145* [비대화형 모드](/ko/headless): 스크린 리더 모드 없이 평문을 작성하는 스크립팅된 `claude -p` 실행145* [비대화형 모드](/docs/ko/headless): 스크린 리더 모드 없이 평문을 작성하는 스크립팅된 `claude -p` 실행

22 22 

23조언자는 대부분의 턴이 일상적이지만 계획 품질이 결과를 결정하는 길고 다단계 작업에 적합합니다. 예시로는 대규모 리팩토링, 오류가 계속 반복되는 디버깅 세션, Claude가 완료를 선언하기 전에 독립적으로 확인하고 싶은 작업이 있습니다.23조언자는 대부분의 턴이 일상적이지만 계획 품질이 결과를 결정하는 길고 다단계 작업에 적합합니다. 예시로는 대규모 리팩토링, 오류가 계속 반복되는 디버깅 세션, Claude가 완료를 선언하기 전에 독립적으로 확인하고 싶은 작업이 있습니다.

24 24 

25계획할 것이 거의 없는 짧은 작업이나 모든 턴에 가장 강력한 모델이 필요한 작업에서는 가치가 적습니다. 이러한 경우 [주 모델을 전환](/ko/model-config#setting-your-model)하거나 [조언자와 opusplan 및 서브에이전트 비교](#compare-with-related-features)를 참고하여 두 번째 의견을 얻는 다른 방법을 확인하세요.25계획할 것이 거의 없는 짧은 작업이나 모든 턴에 가장 강력한 모델이 필요한 작업에서는 가치가 적습니다. 이러한 경우 [주 모델을 전환](/docs/ko/model-config#setting-your-model)하거나 [조언자와 opusplan 및 서브에이전트 비교](#compare-with-related-features)를 참고하여 두 번째 의견을 얻는 다른 방법을 확인하세요.

26 26 

27<h2 id="enable-the-advisor">27<h2 id="enable-the-advisor">

28 조언자 활성화28 조언자 활성화

31조언자 모델을 세 가지 방법으로 설정할 수 있습니다:31조언자 모델을 세 가지 방법으로 설정할 수 있습니다:

32 32 

33* **`/advisor` 명령**: 세션 중간에 조언자를 설정 또는 변경하고 기본값으로 저장33* **`/advisor` 명령**: 세션 중간에 조언자를 설정 또는 변경하고 기본값으로 저장

34* **`advisorModel` 설정**: [설정 파일](/ko/settings)에서 지속적인 기본값 구성34* **`advisorModel` 설정**: [설정 파일](/docs/ko/settings)에서 지속적인 기본값 구성

35* **`--advisor` 플래그**: 시작 시 단일 세션에 대해 조언자 설정35* **`--advisor` 플래그**: 시작 시 단일 세션에 대해 조언자 설정

36 36 

37이 중 하나가 조언자 모델을 설정하면 주 모델이 [이를 지원](#choose-an-advisor-model)하는 세션에 대해 조언자가 활성화됩니다. 사용을 중지하려면 [조언자 끄기](#turn-the-advisor-off)를 참고하세요.37이 중 하나가 조언자 모델을 설정하면 주 모델이 [이를 지원](#choose-an-advisor-model)하는 세션에 대해 조언자가 활성화됩니다. 사용을 중지하려면 [조언자 끄기](#turn-the-advisor-off)를 참고하세요.

38 38 

39<Note>39<Note>

40 Fable 5를 조언자로 사용하려면 Claude Code v2.1.170 이상과 조직의 [Fable 5 액세스](/ko/model-config#work-with-fable-5)가 필요합니다.40 Fable 5를 조언자로 사용하려면 Claude Code v2.1.170 이상과 조직의 [Fable 5 액세스](/docs/ko/model-config#work-with-fable-5)가 필요합니다.

41</Note>41</Note>

42 42 

43<h3 id="use-the-/advisor-command">43<h3 id="use-the-/advisor-command">

50/advisor opus50/advisor opus

51```51```

52 52 

53선택 항목은 사용자 설정의 `advisorModel`에 저장되고 세션 전체에서 유지됩니다. 조직의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록이 저장된 조언자 모델을 제외하면 `/advisor`로 허용된 모델을 선택할 때까지 조언자가 호출되지 않습니다. 현재 주 모델이 조언자를 지원하지 않으면 선택 항목이 여전히 저장되고 [`/model`](/ko/model-config#setting-your-model)을 사용하여 [호환되는 주 모델](#choose-an-advisor-model)로 전환할 때 활성화됩니다.53선택 항목은 사용자 설정의 `advisorModel`에 저장되고 세션 전체에서 유지됩니다. 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록이 저장된 조언자 모델을 제외하면 `/advisor`로 허용된 모델을 선택할 때까지 조언자가 호출되지 않습니다. 현재 주 모델이 조언자를 지원하지 않으면 선택 항목이 여전히 저장되고 [`/model`](/docs/ko/model-config#setting-your-model)을 사용하여 [호환되는 주 모델](#choose-an-advisor-model)로 전환할 때 활성화됩니다.

54 54 

55<h3 id="set-advisormodel-in-settings">55<h3 id="set-advisormodel-in-settings">

56 설정에서 `advisorModel` 설정56 설정에서 `advisorModel` 설정

74claude --advisor opus74claude --advisor opus

75```75```

76 76 

77플래그는 해당 세션에 대해 `advisorModel` 설정보다 우선합니다. 세션의 주 모델이 조언자를 지원하지 않으면 오류로 종료되거나, 요청된 조언자 모델이 조직의 [`availableModels`](/ko/model-config#restrict-model-selection) 허용 목록에서 제외되면 오류로 종료됩니다.77플래그는 해당 세션에 대해 `advisorModel` 설정보다 우선합니다. 세션의 주 모델이 조언자를 지원하지 않으면 오류로 종료되거나, 요청된 조언자 모델이 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에서 제외되면 오류로 종료됩니다.

78 78 

79<h2 id="choose-an-advisor-model">79<h2 id="choose-an-advisor-model">

80 조언자 모델 선택80 조언자 모델 선택

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

84 84 

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

86| ----------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- |86| ------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- |

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

88| Sonnet 4.6 | Fable, Opus, Sonnet | |88| Sonnet 4.6 | Fable, Opus, Sonnet | |

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

90| Opus 4.6 | Fable, Opus, Sonnet 5 | Sonnet 5와 Opus 4.6은 동등한 기능으로 평가되므로 Opus 4.6 주 모델은 Sonnet 5 조언자를 허용합니다 |90| Opus 4.6 | Fable, Opus, Sonnet 5 | Sonnet 5와 Opus 4.6은 동등한 기능으로 평가되므로 Opus 4.6 주 모델은 Sonnet 5 조언자를 허용합니다 |

91| Opus 4.7 이상 | Fable, Opus 4.7, Opus 4.8 | Opus 4.7과 Opus 4.8은 동등한 기능으로 평가되므로 둘 다 다른 하나를 조언자로 허용합니다. Opus 4.6 또는 Sonnet 5 조언자를 가진 Opus 4.7 주 모델은 거부됩니다 |91| Opus 4.7 이상 | Fable, Opus 4.7, Opus 4.8 | Opus 4.7과 Opus 4.8은 동등한 기능으로 평가되므로 둘 다 다른 하나를 조언자로 허용합니다. Opus 4.6 또는 Sonnet 5 조언자를 가진 Opus 4.7 주 모델은 거부됩니다 |

92| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 또는 Sonnet 조언자는 거부됩니다 |92| Fable 5 (v2.1.170+) | Fable | Opus 또는 Sonnet 조언자는 거부됩니다 |

93 93 

94Fable 5는 주 모델로 작동하든 조언자로 작동하든 Claude Code v2.1.170 이상과 Fable 5 액세스가 필요합니다.94Fable 5는 주 모델로 작동하든 조언자로 작동하든 Claude Code v2.1.170 이상과 Fable 5 액세스가 필요합니다.

95 95 

141 141 

142각 조언자 호출은 대화를 조언자 모델로 보내므로 주 모델 사용 외에도 조언자 모델의 요금으로 토큰을 소비합니다. API 청구를 사용하면 조언자 토큰은 조언자 모델의 입력 및 출력 요금으로 청구됩니다. 구독 계획에서 조언자 사용은 계획의 사용 한도에 포함됩니다.142각 조언자 호출은 대화를 조언자 모델로 보내므로 주 모델 사용 외에도 조언자 모델의 요금으로 토큰을 소비합니다. API 청구를 사용하면 조언자 토큰은 조언자 모델의 입력 및 출력 요금으로 청구됩니다. 구독 계획에서 조언자 사용은 계획의 사용 한도에 포함됩니다.

143 143 

144Claude는 모든 턴이 아닌 결정 지점에서 조언자를 호출하므로 더 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 것이 일반적으로 전체 강력한 모델을 실행하는 것보다 비용이 적습니다. 조언자 사용은 [`/usage`](/ko/costs#track-your-costs)에 표시된 세션 합계에 포함됩니다.144Claude는 모든 턴이 아닌 결정 지점에서 조언자를 호출하므로 더 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 것이 일반적으로 전체 강력한 모델을 실행하는 것보다 비용이 적습니다. 조언자 사용은 [`/usage`](/docs/ko/costs#track-your-costs)에 표시된 세션 합계에 포함됩니다.

145 145 

146조언자 토큰이 API 응답에서 보고되는 방식에 대해서는 Claude API 설명서의 [사용량 및 청구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing)를 참고하세요.146조언자 토큰이 API 응답에서 보고되는 방식에 대해서는 Claude API 설명서의 [사용량 및 청구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing)를 참고하세요.

147 147 

149 프롬프트 캐싱에 미치는 영향149 프롬프트 캐싱에 미치는 영향

150</h2>150</h2>

151 151 

152세션 중간에 조언자를 활성화하거나 비활성화해도 주 모델의 [프롬프트 캐시](/ko/prompt-caching)가 무효화되지 않습니다. [모델 또는 노력 수준 변경](/ko/prompt-caching#actions-that-invalidate-the-cache)과 달리 `/advisor` 토글은 캐시된 접두사를 유지하고 조언자가 반환한 지침은 나중의 턴에서 대화 기록의 일부로 캐시됩니다.152세션 중간에 조언자를 활성화하거나 비활성화해도 주 모델의 [프롬프트 캐시](/docs/ko/prompt-caching)가 무효화되지 않습니다. [모델 또는 노력 수준 변경](/docs/ko/prompt-caching#actions-that-invalidate-the-cache)과 달리 `/advisor` 토글은 캐시된 접두사를 유지하고 조언자가 반환한 지침은 나중의 턴에서 대화 기록의 일부로 캐시됩니다.

153 153 

154조언자 모델 자체의 대화 읽기는 캐시되지 않습니다. 각 조언자 호출은 전체 대화를 새로 처리하며 호출 간에 재사용이 없습니다.154조언자 모델 자체의 대화 읽기는 캐시되지 않습니다. 각 조언자 호출은 전체 대화를 새로 처리하며 호출 간에 재사용이 없습니다.

155 155 

159 159 

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

161 161 

162* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. `ANTHROPIC_BASE_URL`로 구성된 [LLM 게이트웨이](/ko/llm-gateway)를 통해 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다.162* **Anthropic API만**: 조언자는 서버 실행 도구입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없습니다. `ANTHROPIC_BASE_URL`로 구성된 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 가용성은 게이트웨이가 요청을 Anthropic API로 그대로 전달하는지 여부에 따라 달라집니다.

163* **지원되는 주 모델**: Opus 4.6 이상, Sonnet 4.6 이상 또는 Haiku 4.5. {/* min-version: 2.1.170 */}Fable 5도 Claude Code v2.1.170 이상에서 적합합니다.163* **지원되는 주 모델**: Opus 4.6 이상, Sonnet 4.6 이상 또는 Haiku 4.5. Fable 5도 Claude Code v2.1.170 이상에서 적합합니다.

164 164 

165<h2 id="turn-the-advisor-off">165<h2 id="turn-the-advisor-off">

166 조언자 끄기166 조언자 끄기

172/advisor off172/advisor off

173```173```

174 174 

175조언자 도구를 완전히 비활성화하려면 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`을 설정하세요. `/advisor` 명령을 사용할 수 없게 되며 구성된 `advisorModel`은 무시됩니다. `--advisor` 플래그는 허용되지만 효과가 없습니다. 이를 전달하는 기존 스크립트는 오류 없이 계속 작동합니다. [환경 변수](/ko/env-vars)를 참고하세요.175조언자 도구를 완전히 비활성화하려면 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`을 설정하세요. `/advisor` 명령을 사용할 수 없게 되며 구성된 `advisorModel`은 무시됩니다. `--advisor` 플래그는 허용되지만 효과가 없습니다. 이를 전달하는 기존 스크립트는 오류 없이 계속 작동합니다. [환경 변수](/docs/ko/env-vars)를 참고하세요.

176 176 

177<h2 id="compare-with-related-features">177<h2 id="compare-with-related-features">

178 관련 기능과 비교178 관련 기능과 비교

183| 접근 방식 | 더 강력한 모델이 실행되는 시기 | 시작 방식 |183| 접근 방식 | 더 강력한 모델이 실행되는 시기 | 시작 방식 |

184| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------- |184| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------- |

185| 조언자 도구 | 작업 중간의 결정 지점에서 | Claude가 지침이 필요할 때 호출합니다 |185| 조언자 도구 | 작업 중간의 결정 지점에서 | Claude가 지침이 필요할 때 호출합니다 |

186| [`opusplan`](/ko/model-config#opusplan-model-setting) | [계획 모드 중 `availableModels`에서 허용될 때](/ko/model-config#restrict-model-selection), 그 다음 실행을 위해 Sonnet으로 전환 | 계획 모드를 입력합니다 |186| [`opusplan`](/docs/ko/model-config#opusplan-model-setting) | [계획 모드 중 `availableModels`에서 허용될 때](/docs/ko/model-config#restrict-model-selection), 그 다음 실행을 위해 Sonnet으로 전환 | 계획 모드를 입력합니다 |

187| [서브에이전트](/ko/sub-agents#choose-a-model) (`model` 설정) | 전체 위임된 부작업에 대해 | Claude가 위임하거나 서브에이전트를 호출합니다 |187| [서브에이전트](/docs/ko/sub-agents#choose-a-model) (`model` 설정) | 전체 위임된 부작업에 대해 | Claude가 위임하거나 서브에이전트를 호출합니다 |

188| [`/model`](/ko/model-config#setting-your-model) | 이후의 모든 턴에 대해 | 모델을 전환합니다 |188| [`/model`](/docs/ko/model-config#setting-your-model) | 이후의 모든 턴에 대해 | 모델을 전환합니다 |

189 189 

190<h2 id="see-also">190<h2 id="see-also">

191 참고 항목191 참고 항목

192</h2>192</h2>

193 193 

194* [모델 구성](/ko/model-config): 모델 전환, 노력 수준 설정, `opusplan` 사용194* [모델 구성](/docs/ko/model-config): 모델 전환, 노력 수준 설정, `opusplan` 사용

195* [비용 효과적으로 관리](/ko/costs): 모델 전체의 토큰 사용량 추적195* [비용 효과적으로 관리](/docs/ko/costs): 모델 전체의 토큰 사용량 추적

196* [Claude API의 조언자 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool): 기본 서버 도구 이해 또는 Messages API에서 직접 사용196* [Claude API의 조언자 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool): 기본 서버 도구 이해 또는 Messages API에서 직접 사용

197* [조언자 전략](https://claude.com/blog/the-advisor-strategy): 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 이유197* [조언자 전략](https://claude.com/blog/the-advisor-strategy): 빠른 주 모델을 더 강력한 조언자와 쌍으로 만드는 이유

26 </Step>26 </Step>

27 27 

28 <Step title="SDK가 등록된 훅을 수집합니다">28 <Step title="SDK가 등록된 훅을 수집합니다">

29 SDK는 해당 이벤트 유형에 대해 등록된 훅을 확인합니다. 여기에는 `options.hooks`에 전달하는 콜백 훅과 해당 [`settingSources`](/ko/agent-sdk/typescript#settingsource) 또는 [`setting_sources`](/ko/agent-sdk/python#settingsource) 항목이 활성화된 경우 설정 파일의 셸 명령 훅이 포함되며, 기본 `query()` 옵션에서는 활성화됩니다.29 SDK는 해당 이벤트 유형에 대해 등록된 훅을 확인합니다. 여기에는 `options.hooks`에 전달하는 콜백 훅과 해당 [`settingSources`](/docs/ko/agent-sdk/typescript#settingsource) 또는 [`setting_sources`](/docs/ko/agent-sdk/python#settingsource) 항목이 활성화된 경우 설정 파일의 셸 명령 훅이 포함되며, 기본 `query()` 옵션에서는 활성화됩니다.

30 </Step>30 </Step>

31 31 

32 <Step title="매처가 실행할 훅을 필터링합니다">32 <Step title="매처가 실행할 훅을 필터링합니다">

155| `PostToolUseFailure` | 예 | 예 | 도구 실행 실패 | 도구 오류 처리 또는 기록 |155| `PostToolUseFailure` | 예 | 예 | 도구 실행 실패 | 도구 오류 처리 또는 기록 |

156| `PostToolBatch` | 아니오 | 예 | 전체 도구 호출 배치가 해결되며, 다음 모델 호출 전에 배치당 한 번 | 전체 배치에 대해 한 번 규칙 주입 |156| `PostToolBatch` | 아니오 | 예 | 전체 도구 호출 배치가 해결되며, 다음 모델 호출 전에 배치당 한 번 | 전체 배치에 대해 한 번 규칙 주입 |

157| `UserPromptSubmit` | 예 | 예 | 사용자 프롬프트 제출 | 프롬프트에 추가 컨텍스트 주입 |157| `UserPromptSubmit` | 예 | 예 | 사용자 프롬프트 제출 | 프롬프트에 추가 컨텍스트 주입 |

158| [`UserPromptExpansion`](/ko/hooks#userpromptexpansion) | 아니오 | 예 | 사용자가 입력한 명령이 Claude에 도달하기 전에 프롬프트로 확장됨 | 명령이 직접 호출되는 것을 차단하거나 스킬이 입력될 때 컨텍스트 추가 |158| [`UserPromptExpansion`](/docs/ko/hooks#userpromptexpansion) | 아니오 | 예 | 사용자가 입력한 명령이 Claude에 도달하기 전에 프롬프트로 확장됨 | 명령이 직접 호출되는 것을 차단하거나 스킬이 입력될 때 컨텍스트 추가 |

159| `MessageDisplay` | 아니오 | 예 | 텍스트가 포함된 어시스턴트 메시지가 완료되며, 전체 메시지 텍스트와 함께 메시지당 한 번 | 기록을 변경하지 않고 표시된 텍스트를 수정하거나 재포맷 |159| `MessageDisplay` | 아니오 | 예 | 텍스트가 포함된 어시스턴트 메시지가 완료되며, 전체 메시지 텍스트와 함께 메시지당 한 번 | 기록을 변경하지 않고 표시된 텍스트를 수정하거나 재포맷 |

160| `Stop` | 예 | 예 | 에이전트 실행 중지 | 종료 전 세션 상태 저장 |160| `Stop` | 예 | 예 | 에이전트 실행 중지 | 종료 전 세션 상태 저장 |

161| `SubagentStart` | 예 | 예 | 서브에이전트 초기화 | 병렬 작업 생성 추적 |161| `SubagentStart` | 예 | 예 | 서브에이전트 초기화 | 병렬 작업 생성 추적 |

213 매처213 매처

214</h3>214</h3>

215 215 

216매처를 사용하여 콜백이 발생할 때를 필터링합니다. `matcher` 필드는 훅 이벤트 유형에 따라 다른 값과 일치합니다. 예를 들어 도구 기반 훅은 도구 이름과 일치하고, `Notification` 훅은 알림 유형과 일치합니다. 각 이벤트 유형에 대한 매처 값의 전체 목록은 [Claude Code 훅 참조](/ko/hooks#matcher-patterns)를 참조하세요.216매처를 사용하여 콜백이 발생할 때를 필터링합니다. `matcher` 필드는 훅 이벤트 유형에 따라 다른 값과 일치합니다. 예를 들어 도구 기반 훅은 도구 이름과 일치하고, `Notification` 훅은 알림 유형과 일치합니다. 각 이벤트 유형에 대한 매처 값의 전체 목록은 [Claude Code 훅 참조](/docs/ko/hooks#matcher-patterns)를 참조하세요.

217 217 

218SDK 매처는 [설정 파일의 매처](/ko/hooks#matcher-patterns)와 동일한 규칙을 따릅니다. 문자, 숫자, `_`, `-`, 공백, `,`, `|`만 포함하는 매처는 정확한 문자열로 비교되며, `|` 또는 `,`로 구분된 대안이 있고 선택적 주변 공백이 있으므로 `Write|Edit`와 `Write, Edit`는 각각 정확히 이 두 도구와 일치하고 `code-reviewer`는 해당 에이전트 유형만 일치합니다. `*` 매처, 빈 문자열, 또는 매처를 완전히 생략하면 이벤트의 모든 발생과 일치합니다.218SDK 매처는 [설정 파일의 매처](/docs/ko/hooks#matcher-patterns)와 동일한 규칙을 따릅니다. 문자, 숫자, `_`, `-`, 공백, `,`, `|`만 포함하는 매처는 정확한 문자열로 비교되며, `|` 또는 `,`로 구분된 대안이 있고 선택적 주변 공백이 있으므로 `Write|Edit`와 `Write, Edit`는 각각 정확히 이 두 도구와 일치하고 `code-reviewer`는 해당 에이전트 유형만 일치합니다. `*` 매처, 빈 문자열, 또는 매처를 완전히 생략하면 이벤트의 모든 발생과 일치합니다.

219 219 

220다른 문자를 포함하는 매처는 앵커되지 않은 정규식으로 평가되므로 `^mcp__`는 모든 MCP 도구와 일치하고 `Edit.*`는 `Edit`과 `NotebookEdit` 모두와 일치합니다. 전체 문자열 일치가 필요할 때는 정규식을 `^`와 `$`로 감싸세요.220다른 문자를 포함하는 매처는 앵커되지 않은 정규식으로 평가되므로 `^mcp__`는 모든 MCP 도구와 일치하고 `Edit.*`는 `Edit`과 `NotebookEdit` 모두와 일치합니다. 전체 문자열 일치가 필요할 때는 정규식을 `^`와 `$`로 감싸세요.

221 221 

225 225 

226| 옵션 | 타입 | 기본값 | 설명 |226| 옵션 | 타입 | 기본값 | 설명 |

227| --------- | ---------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |227| --------- | ---------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

228| `matcher` | `string` | `undefined` | 위의 비교 규칙을 따르는 이벤트의 필터 필드와 일치하는 패턴입니다. 도구 훅의 경우 도구 이름입니다. 기본 제공 도구에는 `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent` 등이 포함됩니다([도구 입력 타입](/ko/agent-sdk/typescript#tool-input-types)에서 전체 목록 참조). MCP 도구는 `mcp__<server>__<action>` 패턴을 사용합니다. |228| `matcher` | `string` | `undefined` | 위의 비교 규칙을 따르는 이벤트의 필터 필드와 일치하는 패턴입니다. 도구 훅의 경우 도구 이름입니다. 기본 제공 도구에는 `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Agent` 등이 포함됩니다([도구 입력 타입](/docs/ko/agent-sdk/typescript#tool-input-types)에서 전체 목록 참조). MCP 도구는 `mcp__<server>__<action>` 패턴을 사용합니다. |

229| `hooks` | `HookCallback[]` | - | 필수입니다. 패턴이 일치할 때 실행할 콜백 함수의 배열 |229| `hooks` | `HookCallback[]` | - | 필수입니다. 패턴이 일치할 때 실행할 콜백 함수의 배열 |

230| `timeout` | `number` | `60` | 초 단위의 타임아웃 |230| `timeout` | `number` | `60` | 초 단위의 타임아웃 |

231 231 

234도구 기반 훅의 경우 매처는 도구 이름으로만 필터링하며, 파일 경로나 다른 인수로는 필터링하지 않습니다. 파일 경로로 필터링하려면 콜백 내에서 `tool_input.file_path`를 확인합니다.234도구 기반 훅의 경우 매처는 도구 이름으로만 필터링하며, 파일 경로나 다른 인수로는 필터링하지 않습니다. 파일 경로로 필터링하려면 콜백 내에서 `tool_input.file_path`를 확인합니다.

235 235 

236<Tip>236<Tip>

237 **도구 이름 발견:** [도구 입력 타입](/ko/agent-sdk/typescript#tool-input-types)에서 기본 제공 도구 이름의 전체 목록을 참조하거나, 매처 없이 훅을 추가하여 세션이 수행하는 모든 도구 호출을 기록합니다.237 **도구 이름 발견:** [도구 입력 타입](/docs/ko/agent-sdk/typescript#tool-input-types)에서 기본 제공 도구 이름의 전체 목록을 참조하거나, 매처 없이 훅을 추가하여 세션이 수행하는 모든 도구 호출을 기록합니다.

238 238 

239 **MCP 도구 이름 지정:** MCP 도구는 항상 `mcp__`로 시작하고 그 뒤에 서버 이름과 작업이 옵니다: `mcp__<server>__<action>`. 예를 들어 `playwright`라는 서버를 구성하면 해당 도구는 `mcp__playwright__browser_screenshot`, `mcp__playwright__browser_click` 등으로 이름이 지정됩니다. 서버 이름은 `mcpServers` 구성에서 사용하는 키에서 나옵니다.239 **MCP 도구 이름 지정:** MCP 도구는 항상 `mcp__`로 시작하고 그 뒤에 서버 이름과 작업이 옵니다: `mcp__<server>__<action>`. 예를 들어 `playwright`라는 서버를 구성하면 해당 도구는 `mcp__playwright__browser_screenshot`, `mcp__playwright__browser_click` 등으로 이름이 지정됩니다. 서버 이름은 `mcpServers` 구성에서 사용하는 키에서 나옵니다.

240</Tip>240</Tip>

249 249 

250모든 훅 콜백은 세 가지 인수를 받습니다:250모든 훅 콜백은 세 가지 인수를 받습니다:

251 251 

252* **입력 데이터:** 이벤트 세부 정보를 포함하는 입력된 객체입니다. 각 훅 유형은 자체 입력 형태를 가집니다. 예를 들어 `PreToolUseHookInput`은 `tool_name`과 `tool_input`을 포함하고, `NotificationHookInput`은 `message`를 포함합니다. [TypeScript](/ko/agent-sdk/typescript#hookinput) 및 [Python](/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 타입 정의를 참조하세요.252* **입력 데이터:** 이벤트 세부 정보를 포함하는 입력된 객체입니다. 각 훅 유형은 자체 입력 형태를 가집니다. 예를 들어 `PreToolUseHookInput`은 `tool_name`과 `tool_input`을 포함하고, `NotificationHookInput`은 `message`를 포함합니다. [TypeScript](/docs/ko/agent-sdk/typescript#hookinput) 및 [Python](/docs/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 타입 정의를 참조하세요.

253 * 모든 훅 입력은 `session_id`, `cwd`, `hook_event_name`을 공유합니다.253 * 모든 훅 입력은 `session_id`, `cwd`, `hook_event_name`을 공유합니다.

254 * `agent_id`와 `agent_type`은 훅이 서브에이전트 내에서 발생할 때 채워집니다. TypeScript에서는 기본 훅 입력에 있으며 모든 훅 유형에서 사용 가능합니다. Python에서는 `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`에서 선택적 필드이며, `SubagentStart`와 `SubagentStop`에서 필수 필드입니다.254 * `agent_id`와 `agent_type`은 훅이 서브에이전트 내에서 발생할 때 채워집니다. TypeScript에서는 기본 훅 입력에 있으며 모든 훅 유형에서 사용 가능합니다. Python에서는 `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`에서 선택적 필드이며, `SubagentStart`와 `SubagentStop`에서 필수 필드입니다.

255* **도구 사용 ID** (`str | None` / `string | undefined`): 동일한 도구 호출에 대해 `PreToolUse` 및 `PostToolUse` 이벤트를 연결합니다.255* **도구 사용 ID** (`str | None` / `string | undefined`): 동일한 도구 호출에 대해 `PreToolUse` 및 `PostToolUse` 이벤트를 연결합니다.

262콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다:262콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다:

263 263 

264* **최상위 필드**는 모든 이벤트에서 동일하게 작동합니다: `systemMessage`는 사용자에게 메시지를 표시하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다.264* **최상위 필드**는 모든 이벤트에서 동일하게 작동합니다: `systemMessage`는 사용자에게 메시지를 표시하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다.

265* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다. `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, `"ask"`, 또는 `"defer"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. `"defer"`를 반환하면 쿼리가 종료되어 [나중에 재개](/ko/hooks#defer-a-tool-call-for-later)할 수 있습니다. `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가할 수 있습니다. 도구의 출력을 Claude가 보기 전에 바꾸려면 `updatedToolOutput`을 설정합니다. 이는 두 SDK 모두에서 모든 도구에 대해 작동합니다. 더 오래된 `updatedMCPToolOutput` 필드는 MCP 도구 출력만 바꾸며 더 이상 사용되지 않습니다.265* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다. `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, `"ask"`, 또는 `"defer"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. `"defer"`를 반환하면 쿼리가 종료되어 [나중에 재개](/docs/ko/hooks#defer-a-tool-call-for-later)할 수 있습니다. `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가할 수 있습니다. 도구의 출력을 Claude가 보기 전에 바꾸려면 `updatedToolOutput`을 설정합니다. 이는 두 SDK 모두에서 모든 도구에 대해 작동합니다. 더 오래된 `updatedMCPToolOutput` 필드는 MCP 도구 출력만 바꾸며 더 이상 사용되지 않습니다.

266 266 

267변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/ko/agent-sdk/typescript#synchookjsonoutput) 및 [Python](/ko/agent-sdk/python#synchookjsonoutput) SDK 참조를 참조하세요.267변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/docs/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/docs/ko/agent-sdk/typescript#synchookjsonoutput) 및 [Python](/docs/ko/agent-sdk/python#synchookjsonoutput) SDK 참조를 참조하세요.

268 268 

269<Note>269<Note>

270 여러 훅 또는 권한 규칙이 적용되는 경우 `deny`는 `defer`보다 우선하고, `defer`는 `ask`보다 우선하고, `ask`는 `allow`보다 우선합니다. 훅이 `deny`를 반환하면 다른 훅에 관계없이 작업이 차단됩니다.270 여러 훅 또는 권한 규칙이 적용되는 경우 `deny`는 `defer`보다 우선하고, `defer`는 `ask`보다 우선하고, `ask`는 `allow`보다 우선합니다. 훅이 `deny`를 반환하면 다른 훅에 관계없이 작업이 차단됩니다.

539 서브에이전트 활동 추적539 서브에이전트 활동 추적

540</h3>540</h3>

541 541 

542`SubagentStop` 훅을 사용하여 서브에이전트가 작업을 완료할 때를 모니터링합니다. [TypeScript](/ko/agent-sdk/typescript#hookinput) 및 [Python](/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 입력 타입을 참조하세요. 이 예제는 서브에이전트가 완료될 때마다 요약을 기록합니다:542`SubagentStop` 훅을 사용하여 서브에이전트가 작업을 완료할 때를 모니터링합니다. [TypeScript](/docs/ko/agent-sdk/typescript#hookinput) 및 [Python](/docs/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 입력 타입을 참조하세요. 이 예제는 서브에이전트가 완료될 때마다 요약을 기록합니다:

543 543 

544<CodeGroup>544<CodeGroup>

545 ```python Python theme={null}545 ```python Python theme={null}

791* 훅 이벤트 이름이 올바르고 대소문자를 구분하는지 확인합니다(`preToolUse`가 아닌 `PreToolUse`).791* 훅 이벤트 이름이 올바르고 대소문자를 구분하는지 확인합니다(`preToolUse`가 아닌 `PreToolUse`).

792* 매처 패턴이 도구 이름과 정확히 일치하는지 확인합니다.792* 매처 패턴이 도구 이름과 정확히 일치하는지 확인합니다.

793* 훅이 `options.hooks`의 올바른 이벤트 유형 아래에 있는지 확인합니다.793* 훅이 `options.hooks`의 올바른 이벤트 유형 아래에 있는지 확인합니다.

794* `Notification` 및 `SubagentStop` 같은 도구가 아닌 훅의 경우 매처는 다른 필드와 일치하며, `Stop`은 매처를 무시합니다([매처 패턴](/ko/hooks#matcher-patterns) 참조).794* `Notification` 및 `SubagentStop` 같은 도구가 아닌 훅의 경우 매처는 다른 필드와 일치하며, `Stop`은 매처를 무시합니다([매처 패턴](/docs/ko/hooks#matcher-patterns) 참조).

795* 에이전트가 [`max_turns`](/ko/agent-sdk/python#claudeagentoptions) 제한에 도달하면 훅이 발생하지 않을 수 있습니다. 세션이 훅을 실행하기 전에 종료되기 때문입니다.795* 에이전트가 [`max_turns`](/docs/ko/agent-sdk/python#claudeagentoptions) 제한에 도달하면 훅이 발생하지 않을 수 있습니다. 세션이 훅을 실행하기 전에 종료되기 때문입니다.

796 796 

797<h3 id="matcher-not-filtering-as-expected">797<h3 id="matcher-not-filtering-as-expected">

798 매처가 예상대로 필터링하지 않음798 매처가 예상대로 필터링하지 않음

818* `HookMatcher` 구성에서 `timeout` 값을 증가시킵니다.818* `HookMatcher` 구성에서 `timeout` 값을 증가시킵니다.

819* TypeScript에서 세 번째 콜백 인수의 `AbortSignal`을 사용하여 취소를 정상적으로 처리합니다.819* TypeScript에서 세 번째 콜백 인수의 `AbortSignal`을 사용하여 취소를 정상적으로 처리합니다.

820 820 

821{/* min-version: 2.1.208 */}타임아웃을 초과하는 `UserPromptSubmit` 또는 [`UserPromptExpansion`](/ko/hooks#userpromptexpansion) 콜백은 해당 프롬프트를 타임아웃 메시지로 차단하고 세션은 계속됩니다. 콜백이 대기 중인 동안 쿼리를 중단하면 대기 중인 도구 호출이 취소됩니다. v2.1.208 이전에는 이러한 이벤트에 대한 콜백 타임아웃이 `error_during_execution`으로 쿼리를 종료했으며, 대기 중인 `PreToolUse` 콜백 중에 중단하면 도구 호출이 진행될 수 있었습니다.821타임아웃을 초과하는 `UserPromptSubmit` 또는 [`UserPromptExpansion`](/docs/ko/hooks#userpromptexpansion) 콜백은 해당 프롬프트를 타임아웃 메시지로 차단하고 세션은 계속됩니다. 콜백이 대기 중인 동안 쿼리를 중단하면 대기 중인 도구 호출이 취소됩니다. v2.1.208 이전에는 이러한 이벤트에 대한 콜백 타임아웃이 `error_during_execution`으로 쿼리를 종료했으며, 대기 중인 `PreToolUse` 콜백 중에 중단하면 도구 호출이 진행될 수 있었습니다.

822 822 

823<h3 id="tool-blocked-unexpectedly">823<h3 id="tool-blocked-unexpectedly">

824 도구가 예기치 않게 차단됨824 도구가 예기치 않게 차단됨

852 Python에서 세션 훅을 사용할 수 없음852 Python에서 세션 훅을 사용할 수 없음

853</h3>853</h3>

854 854 

855`SessionStart` 및 `SessionEnd`는 TypeScript에서 SDK 콜백 훅으로 등록할 수 있지만 Python SDK에서는 사용할 수 없습니다(`HookEvent`는 이를 생략합니다). Python에서는 설정 파일(예: `.claude/settings.json`)에 정의된 [셸 명령 훅](/ko/hooks#hook-events)으로만 사용 가능합니다. SDK 애플리케이션에서 셸 명령 훅을 로드하려면 [`setting_sources`](/ko/agent-sdk/python#settingsource) 또는 [`settingSources`](/ko/agent-sdk/typescript#settingsource)를 사용하여 적절한 설정 소스를 포함합니다:855`SessionStart` 및 `SessionEnd`는 TypeScript에서 SDK 콜백 훅으로 등록할 수 있지만 Python SDK에서는 사용할 수 없습니다(`HookEvent`는 이를 생략합니다). Python에서는 설정 파일(예: `.claude/settings.json`)에 정의된 [셸 명령 훅](/docs/ko/hooks#hook-events)으로만 사용 가능합니다. SDK 애플리케이션에서 셸 명령 훅을 로드하려면 [`setting_sources`](/docs/ko/agent-sdk/python#settingsource) 또는 [`settingSources`](/docs/ko/agent-sdk/typescript#settingsource)를 사용하여 적절한 설정 소스를 포함합니다:

856 856 

857<CodeGroup>857<CodeGroup>

858 ```python Python theme={null}858 ```python Python theme={null}

890 systemMessage가 출력에 나타나지 않음890 systemMessage가 출력에 나타나지 않음

891</h3>891</h3>

892 892 

893`systemMessage` 필드는 사용자에게 메시지를 표시합니다. 기본적으로 SDK는 메시지 스트림에서 훅 출력을 `SessionStart` 및 `Setup` 훅에만 표시하므로 `includeHookEvents`(`Python에서는 include_hook_events`)를 설정하지 않으면 다른 훅 이벤트의 메시지가 나타나지 않습니다. 대신 모델에 컨텍스트를 전달하려면 [`additionalContext`](/ko/hooks#add-context-for-claude)를 반환합니다.893`systemMessage` 필드는 사용자에게 메시지를 표시합니다. 기본적으로 SDK는 메시지 스트림에서 훅 출력을 `SessionStart` 및 `Setup` 훅에만 표시하므로 `includeHookEvents`(`Python에서는 include_hook_events`)를 설정하지 않으면 다른 훅 이벤트의 메시지가 나타나지 않습니다. 대신 모델에 컨텍스트를 전달하려면 [`additionalContext`](/docs/ko/hooks#add-context-for-claude)를 반환합니다.

894 894 

895훅 결정을 애플리케이션에 안정적으로 표시해야 하면 별도로 기록하거나 전용 출력 채널을 사용합니다.895훅 결정을 애플리케이션에 안정적으로 표시해야 하면 별도로 기록하거나 전용 출력 채널을 사용합니다.

896 896 

898 관련 리소스898 관련 리소스

899</h2>899</h2>

900 900 

901* [Claude Code 훅 참조](/ko/hooks): 전체 JSON 입력/출력 스키마, 이벤트 문서 및 매처 패턴901* [Claude Code 훅 참조](/docs/ko/hooks): 전체 JSON 입력/출력 스키마, 이벤트 문서 및 매처 패턴

902* [Claude Code 훅 가이드](/ko/hooks-guide): 셸 명령 훅 예제 및 연습902* [Claude Code 훅 가이드](/docs/ko/hooks-guide): 셸 명령 훅 예제 및 연습

903* [TypeScript SDK 참조](/ko/agent-sdk/typescript): 훅 타입, 입력/출력 정의 및 구성 옵션903* [TypeScript SDK 참조](/docs/ko/agent-sdk/typescript): 훅 타입, 입력/출력 정의 및 구성 옵션

904* [Python SDK 참조](/ko/agent-sdk/python): 훅 타입, 입력/출력 정의 및 구성 옵션904* [Python SDK 참조](/docs/ko/agent-sdk/python): 훅 타입, 입력/출력 정의 및 구성 옵션

905* [권한](/ko/agent-sdk/permissions): 에이전트가 수행할 수 있는 작업 제어905* [권한](/docs/ko/agent-sdk/permissions): 에이전트가 수행할 수 있는 작업 제어

906* [사용자 정의 도구](/ko/agent-sdk/custom-tools): 에이전트 기능을 확장하는 도구 구축906* [사용자 정의 도구](/docs/ko/agent-sdk/custom-tools): 에이전트 기능을 확장하는 도구 구축

6 6 

7> 권한 모드, 훅, 선언적 허용/거부 규칙을 사용하여 에이전트가 도구를 사용하는 방식을 제어합니다.7> 권한 모드, 훅, 선언적 허용/거부 규칙을 사용하여 에이전트가 도구를 사용하는 방식을 제어합니다.

8 8 

9Claude Agent SDK는 Claude가 도구를 사용하는 방식을 관리하기 위한 권한 제어를 제공합니다. 권한 모드와 규칙을 사용하여 자동으로 허용되는 항목을 정의하고, [`canUseTool` 콜백](/ko/agent-sdk/user-input)을 사용하여 런타임에 나머지 모든 항목을 처리합니다.9Claude Agent SDK는 Claude가 도구를 사용하는 방식을 관리하기 위한 권한 제어를 제공합니다. 권한 모드와 규칙을 사용하여 자동으로 허용되는 항목을 정의하고, [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)을 사용하여 런타임에 나머지 모든 항목을 처리합니다.

10 10 

11<Note>11<Note>

12 이 페이지는 권한 모드와 규칙을 다룹니다. 사용자가 런타임에 도구 요청을 승인하거나 거부하는 대화형 승인 흐름을 구축하려면 [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input)를 참조하세요.12 이 페이지는 권한 모드와 규칙을 다룹니다. 사용자가 런타임에 도구 요청을 승인하거나 거부하는 대화형 승인 흐름을 구축하려면 [승인 및 사용자 입력 처리](/docs/ko/agent-sdk/user-input)를 참조하세요.

13</Note>13</Note>

14 14 

15<h2 id="how-permissions-are-evaluated">15<h2 id="how-permissions-are-evaluated">

20 20 

21<Steps>21<Steps>

22 <Step title="훅">22 <Step title="훅">

23 먼저 [훅](/ko/agent-sdk/hooks)을 실행합니다. 훅은 호출을 완전히 거부하거나 통과시킬 수 있습니다. `allow`를 반환하는 훅은 아래의 거부 및 요청 규칙을 건너뛰지 않습니다. 훅 결과와 관계없이 이러한 규칙들이 평가됩니다.23 먼저 [훅](/docs/ko/agent-sdk/hooks)을 실행합니다. 훅은 호출을 완전히 거부하거나 통과시킬 수 있습니다. `allow`를 반환하는 훅은 아래의 거부 및 요청 규칙을 건너뛰지 않습니다. 훅 결과와 관계없이 이러한 규칙들이 평가됩니다.

24 </Step>24 </Step>

25 25 

26 <Step title="거부 규칙">26 <Step title="거부 규칙">

27 `deny` 규칙(`disallowed_tools` 및 [settings.json](/ko/settings#permission-settings)에서)을 확인합니다. 거부 규칙이 일치하면 `bypassPermissions` 모드에서도 도구가 차단됩니다. `Bash`와 같은 단순 이름의 거부 규칙은 이 평가가 시작되기 전에 Claude의 컨텍스트에서 도구를 제거하므로 `Bash(rm *)`와 같은 범위가 지정된 규칙만 이 단계에서 확인됩니다.27 `deny` 규칙(`disallowed_tools` 및 [settings.json](/docs/ko/settings#permission-settings)에서)을 확인합니다. 거부 규칙이 일치하면 `bypassPermissions` 모드에서도 도구가 차단됩니다. `Bash`와 같은 단순 이름의 거부 규칙은 이 평가가 시작되기 전에 Claude의 컨텍스트에서 도구를 제거하므로 `Bash(rm *)`와 같은 범위가 지정된 규칙만 이 단계에서 확인됩니다.

28 </Step>28 </Step>

29 29 

30 <Step title="요청 규칙">30 <Step title="요청 규칙">

31 [settings.json](/ko/settings#permission-settings)에서 `ask` 규칙을 확인합니다. 요청 규칙이 일치하면 `bypassPermissions` 모드에서도 호출이 확인을 위해 [`canUseTool` 콜백](/ko/agent-sdk/user-input)으로 전달됩니다.31 [settings.json](/docs/ko/settings#permission-settings)에서 `ask` 규칙을 확인합니다. 요청 규칙이 일치하면 `bypassPermissions` 모드에서도 호출이 확인을 위해 [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)으로 전달됩니다.

32 32 

33 사용자 상호작용이 필요한 도구는 동일한 방식으로 작동합니다: `AskUserQuestion` 및 서버가 [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)을 설정하는 MCP 도구는 허용 규칙이 일치하는 경우에도 항상 콜백으로 전달됩니다. `dontAsk` 모드에서는 두 경우 모두 거부됩니다. 이 모드는 절대 프롬프트를 표시하지 않기 때문입니다. {/* min-version: 2.1.199 */}MCP 주석에는 Claude Code v2.1.199 이상이 필요합니다.33 사용자 상호작용이 필요한 도구는 동일한 방식으로 작동합니다: `AskUserQuestion` 및 서버가 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)을 설정하는 MCP 도구는 허용 규칙이 일치하는 경우에도 항상 콜백으로 전달됩니다. `dontAsk` 모드에서는 두 경우 모두 거부됩니다. 이 모드는 절대 프롬프트를 표시하지 않기 때문입니다. MCP 주석에는 Claude Code v2.1.199 이상이 필요합니다.

34 34 

35 [claude.ai 커넥터](/ko/mcp#organization-controls-on-connector-tools) 도구는 조직이 `ask`로 설정한 경우 이 단계에서 흐름을 떠납니다. 모든 호출은 `bypassPermissions` 모드에서도, 허용 규칙이 일치하는 경우에도 콜백으로 전달됩니다. 콜백은 `Your organization requires approval for this tool` 이유를 받습니다. `dontAsk` 모드에서는 호출이 거부됩니다. 이 모드는 절대 프롬프트를 표시하지 않기 때문입니다.35 [claude.ai 커넥터](/docs/ko/mcp#organization-controls-on-connector-tools) 도구는 조직이 `ask`로 설정한 경우 이 단계에서 흐름을 떠납니다. 모든 호출은 `bypassPermissions` 모드에서도, 허용 규칙이 일치하는 경우에도 콜백으로 전달됩니다. 콜백은 `Your organization requires approval for this tool` 이유를 받습니다. `dontAsk` 모드에서는 호출이 거부됩니다. 이 모드는 절대 프롬프트를 표시하지 않기 때문입니다.

36 </Step>36 </Step>

37 37 

38 <Step title="권한 모드">38 <Step title="권한 모드">

44 </Step>44 </Step>

45 45 

46 <Step title="canUseTool 콜백">46 <Step title="canUseTool 콜백">

47 위의 어느 것으로도 해결되지 않으면 결정을 위해 [`canUseTool` 콜백](/ko/agent-sdk/user-input)을 호출합니다. `dontAsk` 모드에서는 이 단계를 건너뛰고 도구가 거부됩니다.47 위의 어느 것으로도 해결되지 않으면 결정을 위해 [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)을 호출합니다. `dontAsk` 모드에서는 이 단계를 건너뛰고 도구가 거부됩니다.

48 </Step>48 </Step>

49</Steps>49</Steps>

50 50 

57 57 

58`Bash(ls *)`와 같은 지정자가 있는 항목과 `acceptEdits` 모드는 이를 트리거하지 않으며, 설정 파일에서 오는 허용 규칙은 확인에 표시되지 않습니다.58`Bash(ls *)`와 같은 지정자가 있는 항목과 `acceptEdits` 모드는 이를 트리거하지 않으며, 설정 파일에서 오는 허용 규칙은 확인에 표시되지 않습니다.

59 59 

60`process.on('warning', ...)`으로 수신하고 코드를 일치시켜 로깅하거나 억제합니다. 모드 및 규칙과 관계없이 모든 도구 호출을 제어하려면 대신 [`PreToolUse` 훅](/ko/agent-sdk/hooks)을 사용합니다.60`process.on('warning', ...)`으로 수신하고 코드를 일치시켜 로깅하거나 억제합니다. 모드 및 규칙과 관계없이 모든 도구 호출을 제어하려면 대신 [`PreToolUse` 훅](/docs/ko/agent-sdk/hooks)을 사용합니다.

61 61 

62이 페이지는 **허용 및 거부 규칙**과 **권한 모드**에 중점을 둡니다. 다른 단계의 경우:62이 페이지는 **허용 및 거부 규칙**과 **권한 모드**에 중점을 둡니다. 다른 단계의 경우:

63 63 

64* **훅:** 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. [훅으로 실행 제어](/ko/agent-sdk/hooks)를 참조하세요.64* **훅:** 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. [훅으로 실행 제어](/docs/ko/agent-sdk/hooks)를 참조하세요.

65* **canUseTool 콜백:** 런타임에 사용자에게 승인을 요청합니다. 이전 단계에서 호출이 해결되지 않을 때 사용합니다. [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input)를 참조하세요.65* **canUseTool 콜백:** 런타임에 사용자에게 승인을 요청합니다. 이전 단계에서 호출이 해결되지 않을 때 사용합니다. [승인 및 사용자 입력 처리](/docs/ko/agent-sdk/user-input)를 참조하세요.

66 66 

67<h2 id="allow-and-deny-rules">67<h2 id="allow-and-deny-rules">

68 허용 및 거부 규칙68 허용 및 거부 규칙

81 81 

82`Read` 및 `Edit`에 대한 범위 규칙은 경로 패턴을 사용합니다. `Edit(path)` 규칙은 `Write` 및 `NotebookEdit`을 포함하여 파일을 쓰는 모든 기본 제공 도구를 관리합니다. `Write(path)` 규칙은 파일 권한 검사에 의해 절대 일치하지 않습니다.82`Read` 및 `Edit`에 대한 범위 규칙은 경로 패턴을 사용합니다. `Edit(path)` 규칙은 `Write` 및 `NotebookEdit`을 포함하여 파일을 쓰는 모든 기본 제공 도구를 관리합니다. `Write(path)` 규칙은 파일 권한 검사에 의해 절대 일치하지 않습니다.

83 83 

84절대 파일 시스템 경로에는 `//path`를 사용합니다. `Edit(//secrets/**)` 거부 규칙은 디스크의 `/secrets` 아래 어디든지 쓰기를 차단합니다. 단일 선행 슬래시를 사용하면 `Edit(/secrets/**)`는 규칙의 소스에서 앵커됩니다. `allowed_tools` 또는 `disallowed_tools`를 통해 전달된 규칙의 경우, 이는 세션의 작업 디렉토리를 의미하므로 규칙은 디스크의 `/secrets`를 차단하지 않습니다. [Read 및 Edit 규칙](/ko/permissions#read-and-edit)에서 네 가지 앵커 형식과 설정 파일의 규칙이 어떻게 해결되는지 확인하세요.84절대 파일 시스템 경로에는 `//path`를 사용합니다. `Edit(//secrets/**)` 거부 규칙은 디스크의 `/secrets` 아래 어디든지 쓰기를 차단합니다. 단일 선행 슬래시를 사용하면 `Edit(/secrets/**)`는 규칙의 소스에서 앵커됩니다. `allowed_tools` 또는 `disallowed_tools`를 통해 전달된 규칙의 경우, 이는 세션의 작업 디렉토리를 의미하므로 규칙은 디스크의 `/secrets`를 차단하지 않습니다. [Read 및 Edit 규칙](/docs/ko/permissions#read-and-edit)에서 네 가지 앵커 형식과 설정 파일의 규칙이 어떻게 해결되는지 확인하세요.

85 85 

86<Warning>86<Warning>

87 **자동 승인된 도구는 절대 `canUseTool`에 도달하지 않습니다.** `acceptEdits` 또는 `bypassPermissions`에 의해, 또는 허용 규칙에 의해 이전 단계에서 승인된 도구 호출은 `canUseTool` 콜백을 건너뛰므로 거기에 배치한 권한 검사는 해당 도구에 대해 자동으로 무시됩니다. `AskUserQuestion`, [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구, 및 커넥터 도구([조직이 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools))는 허용 규칙이 일치할 때에도 콜백에 도달합니다.87 **자동 승인된 도구는 절대 `canUseTool`에 도달하지 않습니다.** `acceptEdits` 또는 `bypassPermissions`에 의해, 또는 허용 규칙에 의해 이전 단계에서 승인된 도구 호출은 `canUseTool` 콜백을 건너뛰므로 거기에 배치한 권한 검사는 해당 도구에 대해 자동으로 무시됩니다. `AskUserQuestion`, [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구, 및 커넥터 도구([조직이 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools))는 허용 규칙이 일치할 때에도 콜백에 도달합니다.

88 88 

89 적용 범위는 항목의 형식에 따라 달라집니다. `Read` 또는 `mcp__github__get_issue`와 같은 단순 이름은 해당 도구에 대한 모든 호출을 자동 승인하는 반면, `Bash(ls *)`와 같은 범위 규칙은 일치하는 호출만 자동 승인하고 다른 `Bash` 호출은 여전히 콜백으로 통과합니다. 모든 도구 호출에서 실행되어야 하는 검사의 경우 [`PreToolUse` 훅](/ko/agent-sdk/hooks)을 사용합니다. 훅은 다른 모든 단계 이전에 실행되며, 훅 거부는 `bypassPermissions` 모드에서도 적용됩니다.89 적용 범위는 항목의 형식에 따라 달라집니다. `Read` 또는 `mcp__github__get_issue`와 같은 단순 이름은 해당 도구에 대한 모든 호출을 자동 승인하는 반면, `Bash(ls *)`와 같은 범위 규칙은 일치하는 호출만 자동 승인하고 다른 `Bash` 호출은 여전히 콜백으로 통과합니다. 모든 도구 호출에서 실행되어야 하는 검사의 경우 [`PreToolUse` 훅](/docs/ko/agent-sdk/hooks)을 사용합니다. 훅은 다른 모든 단계 이전에 실행되며, 훅 거부는 `bypassPermissions` 모드에서도 적용됩니다.

90</Warning>90</Warning>

91 91 

92잠금된 에이전트의 경우 `allowedTools`를 `permissionMode: "dontAsk"`와 쌍으로 사용합니다. 나열된 도구는 승인되고, 위의 경고에서 항상 프롬프트하는 도구를 제외하고 다른 모든 항목은 프롬프트 대신 완전히 거부됩니다:92잠금된 에이전트의 경우 `allowedTools`를 `permissionMode: "dontAsk"`와 쌍으로 사용합니다. 나열된 도구는 승인되고, 위의 경고에서 항상 프롬프트하는 도구를 제외하고 다른 모든 항목은 프롬프트 대신 완전히 거부됩니다:

102 **`allowed_tools`는 `bypassPermissions`를 제한하지 않습니다.** `allowed_tools`는 나열한 도구만 사전 승인합니다. 나열되지 않은 도구는 허용 규칙과 일치하지 않으며 권한 모드로 통과하며, 여기서 `bypassPermissions`는 이를 승인합니다. `allowed_tools=["Read"]`를 `permission_mode="bypassPermissions"`와 함께 설정하면 `Bash`, `Write`, `Edit`을 포함한 모든 도구가 여전히 승인됩니다. `bypassPermissions`가 필요하지만 특정 도구를 차단하려면 `disallowed_tools`를 사용합니다.102 **`allowed_tools`는 `bypassPermissions`를 제한하지 않습니다.** `allowed_tools`는 나열한 도구만 사전 승인합니다. 나열되지 않은 도구는 허용 규칙과 일치하지 않으며 권한 모드로 통과하며, 여기서 `bypassPermissions`는 이를 승인합니다. `allowed_tools=["Read"]`를 `permission_mode="bypassPermissions"`와 함께 설정하면 `Bash`, `Write`, `Edit`을 포함한 모든 도구가 여전히 승인됩니다. `bypassPermissions`가 필요하지만 특정 도구를 차단하려면 `disallowed_tools`를 사용합니다.

103</Warning>103</Warning>

104 104 

105`.claude/settings.json`에서 허용, 거부 및 요청 규칙을 선언적으로 구성할 수도 있습니다. 이러한 규칙은 `project` 설정 소스가 활성화될 때 읽혀지며, 기본 `query()` 옵션에 대해 활성화됩니다. `setting_sources`(TypeScript: `settingSources`)를 명시적으로 설정하면 적용되도록 `"project"`를 포함합니다. 규칙 구문은 [권한 설정](/ko/settings#permission-settings)을 참조하세요.105`.claude/settings.json`에서 허용, 거부 및 요청 규칙을 선언적으로 구성할 수도 있습니다. 이러한 규칙은 `project` 설정 소스가 활성화될 때 읽혀지며, 기본 `query()` 옵션에 대해 활성화됩니다. `setting_sources`(TypeScript: `settingSources`)를 명시적으로 설정하면 적용되도록 `"project"`를 포함합니다. 규칙 구문은 [권한 설정](/docs/ko/settings#permission-settings)을 참조하세요.

106 106 

107<h2 id="permission-modes">107<h2 id="permission-modes">

108 권한 모드108 권한 모드

119| 모드 | 설명 | 도구 동작 |119| 모드 | 설명 | 도구 동작 |

120| :------------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |120| :------------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

121| `default` | 표준 권한 동작 | 자동 승인 없음; 일치하지 않는 도구는 `canUseTool` 콜백을 트리거합니다 |121| `default` | 표준 권한 동작 | 자동 승인 없음; 일치하지 않는 도구는 `canUseTool` 콜백을 트리거합니다 |

122| `dontAsk` | 프롬프트 대신 거부 | `allowed_tools` 또는 규칙으로 사전 승인되지 않은 항목은 거부됩니다; 커넥터 도구 [조직에서 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 사전 승인했더라도 거부됩니다. `canUseTool`은 호출되지 않습니다 |122| `dontAsk` | 프롬프트 대신 거부 | `allowed_tools` 또는 규칙으로 사전 승인되지 않은 항목은 거부됩니다; 커넥터 도구 [조직에서 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 사전 승인했더라도 거부됩니다. `canUseTool`은 호출되지 않습니다 |

123| `acceptEdits` | 파일 편집 자동 수락 | 파일 편집 및 [파일 시스템 작업](#accept-edits-mode-acceptedits)(`mkdir`, `rm`, `mv` 등)이 자동으로 승인됩니다 |123| `acceptEdits` | 파일 편집 자동 수락 | 파일 편집 및 [파일 시스템 작업](#accept-edits-mode-acceptedits)(`mkdir`, `rm`, `mv` 등)이 자동으로 승인됩니다 |

124| `bypassPermissions` | 권한 확인 무시 | 도구는 권한 프롬프트 없이 실행됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated)이 일치하는 경우, 커넥터 도구 [조직에서 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 제외됩니다(주의해서 사용) |124| `bypassPermissions` | 권한 확인 무시 | 도구는 권한 프롬프트 없이 실행됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated)이 일치하는 경우, 커넥터 도구 [조직에서 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 제외됩니다(주의해서 사용) |

125| `plan` | 계획 모드 | Claude는 소스 파일을 편집하지 않고 탐색 및 계획합니다. 파일 편집은 자동으로 승인되지 않으며 `canUseTool` 콜백을 통해 프롬프트합니다 |125| `plan` | 계획 모드 | Claude는 소스 파일을 편집하지 않고 탐색 및 계획합니다. 파일 편집은 자동으로 승인되지 않으며 `canUseTool` 콜백을 통해 프롬프트합니다 |

126| `auto` | 모델 분류 승인 | 모델 분류기가 각 도구 호출을 승인하거나 거부합니다. [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 가용성을 참조하세요 |126| `auto` | 모델 분류 승인 | 모델 분류기가 각 도구 호출을 승인하거나 거부합니다. [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 가용성을 참조하세요 |

127 127 

128<Warning>128<Warning>

129 **하위 에이전트 상속:** 부모가 `bypassPermissions`, `acceptEdits` 또는 `auto`를 사용할 때 모든 하위 에이전트는 해당 모드를 상속하며 하위 에이전트별로 재정의할 수 없습니다. 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트와 덜 제한된 동작을 가질 수 있으므로 `bypassPermissions`를 상속하면 전체 자율 시스템 액세스 권한이 부여됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated), 커넥터 도구 [조직에서 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools), 및 사용자 상호작용이 필요한 도구는 여전히 프롬프트를 강제합니다.129 **하위 에이전트 상속:** 부모가 `bypassPermissions`, `acceptEdits` 또는 `auto`를 사용할 때 모든 하위 에이전트는 해당 모드를 상속하며 하위 에이전트별로 재정의할 수 없습니다. 하위 에이전트는 주 에이전트와 다른 시스템 프롬프트와 덜 제한된 동작을 가질 수 있으므로 `bypassPermissions`를 상속하면 전체 자율 시스템 액세스 권한이 부여됩니다. 명시적 [`ask` 규칙](#how-permissions-are-evaluated), 커넥터 도구 [조직에서 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools), 및 사용자 상호작용이 필요한 도구는 여전히 프롬프트를 강제합니다.

130</Warning>130</Warning>

131 131 

132<h3 id="set-permission-mode">132<h3 id="set-permission-mode">

260 요청 안 함 모드 (`dontAsk`)260 요청 안 함 모드 (`dontAsk`)

261</h4>261</h4>

262 262 

263모든 권한 프롬프트를 거부로 변환합니다. `allowed_tools`, `settings.json` 허용 규칙 또는 훅으로 사전 승인된 도구는 정상적으로 실행됩니다. 커넥터 도구 [조직에서 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 허용 규칙이 일치하더라도 거부됩니다. 다른 모든 항목은 `canUseTool`을 호출하지 않고 거부됩니다.263모든 권한 프롬프트를 거부로 변환합니다. `allowed_tools`, `settings.json` 허용 규칙 또는 훅으로 사전 승인된 도구는 정상적으로 실행됩니다. 커넥터 도구 [조직에서 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 허용 규칙이 일치하더라도 거부됩니다. 다른 모든 항목은 `canUseTool`을 호출하지 않고 거부됩니다.

264 264 

265**사용 시기:** 헤드리스 에이전트에 대해 고정된 명시적 도구 표면을 원하고 `canUseTool`이 없을 때의 자동 거부보다 하드 거부를 선호할 때입니다.265**사용 시기:** 헤드리스 에이전트에 대해 고정된 명시적 도구 표면을 원하고 `canUseTool`이 없을 때의 자동 거부보다 하드 거부를 선호할 때입니다.

266 266 

273<Warning>273<Warning>

274 극도의 주의를 기울여 사용하세요. Claude는 이 모드에서 전체 시스템 액세스 권한을 가집니다. 모든 가능한 작업을 신뢰하는 제어된 환경에서만 사용하세요.274 극도의 주의를 기울여 사용하세요. Claude는 이 모드에서 전체 시스템 액세스 권한을 가집니다. 모든 가능한 작업을 신뢰하는 제어된 환경에서만 사용하세요.

275 275 

276 `allowed_tools`는 이 모드를 제한하지 않습니다. 나열한 도구뿐만 아니라 모든 도구가 승인됩니다. 거부 규칙(`disallowed_tools`), 명시적 `ask` 규칙 및 훅은 모드 확인 전에 평가되며 여전히 도구를 차단할 수 있습니다. 커넥터 도구 [조직에서 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 여전히 `canUseTool` 콜백으로 넘어갑니다.276 `allowed_tools`는 이 모드를 제한하지 않습니다. 나열한 도구뿐만 아니라 모든 도구가 승인됩니다. 거부 규칙(`disallowed_tools`), 명시적 `ask` 규칙 및 훅은 모드 확인 전에 평가되며 여전히 도구를 차단할 수 있습니다. 커넥터 도구 [조직에서 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)하고 사용자 상호작용이 필요한 도구는 여전히 `canUseTool` 콜백으로 넘어갑니다.

277</Warning>277</Warning>

278 278 

279<h4 id="plan-mode-plan">279<h4 id="plan-mode-plan">

280 계획 모드 (`plan`)280 계획 모드 (`plan`)

281</h4>281</h4>

282 282 

283Claude는 코드베이스를 탐색하고 소스 파일을 편집하지 않고 계획을 생성합니다. 읽기 전용 도구는 기본 모드처럼 실행됩니다. 파일 편집은 계획 모드에서 자동으로 승인되지 않으며, 허용 규칙이 일치하더라도 `canUseTool` 콜백을 통해 프롬프트합니다. Claude는 계획을 최종화하기 전에 요구 사항을 명확히 하기 위해 `AskUserQuestion`을 사용할 수 있습니다. [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input#handle-clarifying-questions)에서 이러한 프롬프트 처리를 참조하세요.283Claude는 코드베이스를 탐색하고 소스 파일을 편집하지 않고 계획을 생성합니다. 읽기 전용 도구는 기본 모드처럼 실행됩니다. 파일 편집은 계획 모드에서 자동으로 승인되지 않으며, 허용 규칙이 일치하더라도 `canUseTool` 콜백을 통해 프롬프트합니다. Claude는 계획을 최종화하기 전에 요구 사항을 명확히 하기 위해 `AskUserQuestion`을 사용할 수 있습니다. [승인 및 사용자 입력 처리](/docs/ko/agent-sdk/user-input#handle-clarifying-questions)에서 이러한 프롬프트 처리를 참조하세요.

284 284 

285**사용 시기:** Claude가 변경 사항을 실행하지 않고 제안하기를 원할 때, 예를 들어 코드 검토 중이거나 변경 사항이 적용되기 전에 승인해야 할 때입니다.285**사용 시기:** Claude가 변경 사항을 실행하지 않고 제안하기를 원할 때, 예를 들어 코드 검토 중이거나 변경 사항이 적용되기 전에 승인해야 할 때입니다.

286 286 

290 290 

291권한 평가 흐름의 다른 단계의 경우:291권한 평가 흐름의 다른 단계의 경우:

292 292 

293* [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input): 대화형 승인 프롬프트 및 명확히 하는 질문293* [승인 및 사용자 입력 처리](/docs/ko/agent-sdk/user-input): 대화형 승인 프롬프트 및 명확히 하는 질문

294* [훅 가이드](/ko/agent-sdk/hooks): 에이전트 수명 주기의 주요 지점에서 사용자 정의 코드 실행294* [훅 가이드](/docs/ko/agent-sdk/hooks): 에이전트 수명 주기의 주요 지점에서 사용자 정의 코드 실행

295* [권한 규칙](/ko/settings#permission-settings): `settings.json`의 선언적 허용/거부 규칙295* [권한 규칙](/docs/ko/settings#permission-settings): `settings.json`의 선언적 허용/거부 규칙

18pip install claude-agent-sdk18pip install claude-agent-sdk

19```19```

20 20 

21uv, Windows PowerShell, 및 API 키 설정에 대해서는 [Agent SDK 개요에서 시작하기](/ko/agent-sdk/overview#get-started)를 참조하십시오.21uv, Windows PowerShell, 및 API 키 설정에 대해서는 [Agent SDK 개요에서 시작하기](/docs/ko/agent-sdk/overview#get-started)를 참조하십시오.

22 22 

23<h2 id="choosing-between-query-and-claudesdkclient">23<h2 id="choosing-between-query-and-claudesdkclient">

24 `query()`와 `ClaudeSDKClient` 중 선택하기24 `query()`와 `ClaudeSDKClient` 중 선택하기

73 `query()`73 `query()`

74</h3>74</h3>

75 75 

76Claude Code와의 각 상호작용을 위해 기본적으로 새 세션을 생성합니다. 메시지가 도착하면 생성하는 비동기 반복자를 반환합니다. `query()`에 대한 각 호출은 `continue_conversation=True` 또는 [`ClaudeAgentOptions`](#claudeagentoptions)에서 `resume`을 전달하지 않는 한 이전 상호작용의 메모리 없이 새로 시작합니다. [세션](/ko/agent-sdk/sessions)을 참조하세요.76Claude Code와의 각 상호작용을 위해 기본적으로 새 세션을 생성합니다. 메시지가 도착하면 생성하는 비동기 반복자를 반환합니다. `query()`에 대한 각 호출은 `continue_conversation=True` 또는 [`ClaudeAgentOptions`](#claudeagentoptions)에서 `resume`을 전달하지 않는 한 이전 상호작용의 메모리 없이 새로 시작합니다. [세션](/docs/ko/agent-sdk/sessions)을 참조하세요.

77 77 

78```python theme={null}78```python theme={null}

79async def query(79async def query(

565| `interrupt()` | 중단 신호 전송 (스트리밍 모드에서만 작동) |565| `interrupt()` | 중단 신호 전송 (스트리밍 모드에서만 작동) |

566| `set_permission_mode(mode)` | 현재 세션의 권한 모드 변경 |566| `set_permission_mode(mode)` | 현재 세션의 권한 모드 변경 |

567| `set_model(model)` | 현재 세션의 모델 변경. 기본값으로 재설정하려면 `None` 전달 |567| `set_model(model)` | 현재 세션의 모델 변경. 기본값으로 재설정하려면 `None` 전달 |

568| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |568| `rewind_files(user_message_id)` | 지정된 사용자 메시지의 상태로 파일 복원. `enable_file_checkpointing=True` 필요. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |

569| `get_mcp_status()` | 구성된 모든 MCP 서버의 상태 가져오기. [`McpStatusResponse`](#mcpstatusresponse) 반환 |569| `get_mcp_status()` | 구성된 모든 MCP 서버의 상태 가져오기. [`McpStatusResponse`](#mcpstatusresponse) 반환 |

570| `reconnect_mcp_server(server_name)` | 실패했거나 연결이 끊긴 MCP 서버에 다시 연결 시도 |570| `reconnect_mcp_server(server_name)` | 실패했거나 연결이 끊긴 MCP 서버에 다시 연결 시도 |

571| `toggle_mcp_server(server_name, enabled)` | 세션 중간에 MCP 서버 활성화 또는 비활성화. 비활성화하면 도구 제거 |571| `toggle_mcp_server(server_name, enabled)` | 세션 중간에 MCP 서버 활성화 또는 비활성화. 비활성화하면 도구 제거 |

907| 속성 | 타입 | 기본값 | 설명 |907| 속성 | 타입 | 기본값 | 설명 |

908| :---------------------------- | :------------------------------------------------------------------------------------ | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |908| :---------------------------- | :------------------------------------------------------------------------------------ | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

909| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 도구 구성. Claude Code의 기본 도구를 위해 `{"type": "preset", "preset": "claude_code"}` 사용 |909| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 도구 구성. Claude Code의 기본 도구를 위해 `{"type": "preset", "preset": "claude_code"}` 사용 |

910| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |910| `allowed_tools` | `list[str]` | `[]` | 프롬프트 없이 자동 승인할 도구. 이것은 Claude를 이 도구로만 제한하지 않습니다. 나열되지 않은 도구는 `permission_mode` 및 `can_use_tool`로 넘어갑니다. `disallowed_tools`를 사용하여 도구를 차단합니다. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

911| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 `{"type": "preset", "preset": "claude_code"}`를 선택적 `"append"`와 함께 사용하거나, `{"type": "file", "path": "..."}` 형식으로 디스크에서 큰 프롬프트를 로드합니다. [`SystemPromptPreset`](#systempromptpreset) 및 [`SystemPromptFile`](#systempromptfile) 참조 |911| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 시스템 프롬프트 구성. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 위해 `{"type": "preset", "preset": "claude_code"}`를 선택적 `"append"`와 함께 사용하거나, `{"type": "file", "path": "..."}` 형식으로 디스크에서 큰 프롬프트를 로드합니다. [`SystemPromptPreset`](#systempromptpreset) 및 [`SystemPromptFile`](#systempromptfile) 참조 |

912| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 서버 구성 또는 구성 파일 경로 |912| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 서버 구성 또는 구성 파일 경로 |

913| `strict_mcp_config` | `bool` | `False` | `True`일 때, `mcp_servers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인 제공 MCP 서버 및 [claude.ai 커넥터](/ko/mcp#use-mcp-servers-from-claude-ai)를 무시합니다. CLI `--strict-mcp-config` 플래그에 매핑됩니다 |913| `strict_mcp_config` | `bool` | `False` | `True`일 때, `mcp_servers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인 제공 MCP 서버 및 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai)를 무시합니다. CLI `--strict-mcp-config` 플래그에 매핑됩니다 |

914| `permission_mode` | `PermissionMode \| None` | `None` | 도구 사용을 위한 권한 모드 |914| `permission_mode` | `PermissionMode \| None` | `None` | 도구 사용을 위한 권한 모드 |

915| `continue_conversation` | `bool` | `False` | 가장 최신 대화 계속하기 |915| `continue_conversation` | `bool` | `False` | 가장 최신 대화 계속하기 |

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

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

918| `max_budget_usd` | `float \| None` | `None` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리 중지. `total_cost_usd`와 동일한 추정과 비교됨. 정확도 주의 사항은 [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking) 참조 |918| `max_budget_usd` | `float \| None` | `None` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리 중지. `total_cost_usd`와 동일한 추정과 비교됨. 정확도 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking) 참조 |

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

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

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

922| `fallback_model` | `str \| None` | `None` | 기본 모델이 실패할 경우 사용할 폴백 모델 |922| `fallback_model` | `str \| None` | `None` | 기본 모델이 실패할 경우 사용할 폴백 모델 |

923| `betas` | `list[SdkBeta]` | `[]` | 활성화할 베타 기능. 사용 가능한 옵션은 [`SdkBeta`](#sdkbeta) 참조 |923| `betas` | `list[SdkBeta]` | `[]` | 활성화할 베타 기능. 사용 가능한 옵션은 [`SdkBeta`](#sdkbeta) 참조 |

924| `output_format` | `dict[str, Any] \| None` | `None` | 구조화된 응답을 위한 출력 형식 (예: `{"type": "json_schema", "schema": {...}}`). 자세한 내용은 [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조 |924| `output_format` | `dict[str, Any] \| None` | `None` | 구조화된 응답을 위한 출력 형식 (예: `{"type": "json_schema", "schema": {...}}`). 자세한 내용은 [구조화된 출력](/docs/ko/agent-sdk/structured-outputs) 참조 |

925| `permission_prompt_tool_name` | `str \| None` | `None` | 권한 프롬프트를 위한 MCP 도구 이름 |925| `permission_prompt_tool_name` | `str \| None` | `None` | 권한 프롬프트를 위한 MCP 도구 이름 |

926| `cwd` | `str \| Path \| None` | `None` | 현재 작업 디렉토리 |926| `cwd` | `str \| Path \| None` | `None` | 현재 작업 디렉토리 |

927| `cli_path` | `str \| Path \| None` | `None` | Claude Code CLI 실행 파일의 사용자 정의 경로 |927| `cli_path` | `str \| Path \| None` | `None` | Claude Code CLI 실행 파일의 사용자 정의 경로 |

928| `settings` | `str \| None` | `None` | 설정 파일 경로 |928| `settings` | `str \| None` | `None` | 설정 파일 경로 |

929| `add_dirs` | `list[str \| Path]` | `[]` | Claude가 접근할 수 있는 추가 디렉토리 |929| `add_dirs` | `list[str \| Path]` | `[]` | Claude가 접근할 수 있는 추가 디렉토리 |

930| `env` | `dict[str, str]` | `{}` | 상속된 프로세스 환경 위에 병합된 환경 변수. 기본 CLI가 읽는 변수는 [환경 변수](/ko/env-vars) 참조. 시간 초과 관련 변수는 [느리거나 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses) 참조 |930| `env` | `dict[str, str]` | `{}` | 상속된 프로세스 환경 위에 병합된 환경 변수. 기본 CLI가 읽는 변수는 [환경 변수](/docs/ko/env-vars) 참조. 시간 초과 관련 변수는 [느리거나 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses) 참조 |

931| `extra_args` | `dict[str, str \| None]` | `{}` | CLI에 직접 전달할 추가 CLI 인수 |931| `extra_args` | `dict[str, str \| None]` | `{}` | CLI에 직접 전달할 추가 CLI 인수 |

932| `max_buffer_size` | `int \| None` | `None` | CLI stdout 버퍼링 시 최대 바이트 |932| `max_buffer_size` | `int \| None` | `None` | CLI stdout 버퍼링 시 최대 바이트 |

933| `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - 디버그 출력을 위한 파일 유사 객체. 대신 `stderr` 콜백 사용 |933| `debug_stderr` | `Any` | `sys.stderr` | *Deprecated* - 디버그 출력을 위한 파일 유사 객체. 대신 `stderr` 콜백 사용 |

934| `stderr` | `Callable[[str], None] \| None` | `None` | CLI의 stderr 출력을 위한 콜백 함수 |934| `stderr` | `Callable[[str], None] \| None` | `None` | CLI의 stderr 출력을 위한 콜백 함수 |

935| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 도구 권한 콜백 함수. [권한 흐름](/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowed_tools`, 허용 규칙 또는 `permission_mode`로 자동 승인된 호출에 대해서는 호출되지 않습니다. `AskUserQuestion`, 커넥터 도구 [조직이 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools), 및 [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치하더라도 이에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다. [`CanUseTool`](#canusetool)에서 자세한 내용 참조 |935| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 도구 권한 콜백 함수. [권한 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowed_tools`, 허용 규칙 또는 `permission_mode`로 자동 승인된 호출에 대해서는 호출되지 않습니다. `AskUserQuestion`, 커넥터 도구 [조직이 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools), 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치하더라도 이에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다. [`CanUseTool`](#canusetool)에서 자세한 내용 참조 |

936| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | 이벤트 가로채기를 위한 hook 구성 |936| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | 이벤트 가로채기를 위한 hook 구성 |

937| `user` | `str \| None` | `None` | 사용자 식별자 |937| `user` | `str \| None` | `None` | 사용자 식별자 |

938| `include_partial_messages` | `bool` | `False` | 부분 메시지 스트리밍 이벤트 포함. 활성화되면 [`StreamEvent`](#streamevent) 메시지가 생성됩니다 |938| `include_partial_messages` | `bool` | `False` | 부분 메시지 스트리밍 이벤트 포함. 활성화되면 [`StreamEvent`](#streamevent) 메시지가 생성됩니다 |

939| `include_hook_events` | `bool` | `False` | 메시지 스트림에 hook 라이프사이클 이벤트를 `HookEventMessage` 객체로 포함 |939| `include_hook_events` | `bool` | `False` | 메시지 스트림에 hook 라이프사이클 이벤트를 `HookEventMessage` 객체로 포함 |

940| `fork_session` | `bool` | `False` | `resume`으로 재개할 때, 원본 세션을 계속하는 대신 새 세션 ID로 포크합니다 |940| `fork_session` | `bool` | `False` | `resume`으로 재개할 때, 원본 세션을 계속하는 대신 새 세션 ID로 포크합니다 |

941| `agents` | `dict[str, AgentDefinition] \| None` | `None` | 프로그래밍 방식으로 정의된 서브에이전트 |941| `agents` | `dict[str, AgentDefinition] \| None` | `None` | 프로그래밍 방식으로 정의된 서브에이전트 |

942| `plugins` | `list[SdkPluginConfig]` | `[]` | 로컬 경로에서 사용자 정의 플러그인 로드. 자세한 내용은 [플러그인](/ko/agent-sdk/plugins) 참조 |942| `plugins` | `list[SdkPluginConfig]` | `[]` | 로컬 경로에서 사용자 정의 플러그인 로드. 자세한 내용은 [플러그인](/docs/ko/agent-sdk/plugins) 참조 |

943| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | 프로그래밍 방식으로 샌드박스 동작 구성. 자세한 내용은 [샌드박스 설정](#sandboxsettings) 참조 |943| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | 프로그래밍 방식으로 샌드박스 동작 구성. 자세한 내용은 [샌드박스 설정](#sandboxsettings) 참조 |

944| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI 기본값: 모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`를 전달합니다. 관리형 정책 설정은 어쨌든 로드됩니다. 서버 관리 설정은 [적격 구성](/ko/server-managed-settings#platform-availability)에서 조직 자격증명으로 세션이 인증될 때 가져옵니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법 참조 |944| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI 기본값: 모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`를 전달합니다. 관리형 정책 설정은 어쨌든 로드됩니다. 서버 관리 설정은 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 조직 자격증명으로 세션이 인증될 때 가져옵니다. [Claude Code 기능 사용](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법 참조 |

945| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowed_tools`에 Skill 도구를 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `"Skill"`을 포함합니다. [스킬](/ko/agent-sdk/skills) 참조 |945| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 세션에서 사용 가능한 스킬. 모든 발견된 스킬을 활성화하려면 `"all"`을 전달하거나, 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowed_tools`에 Skill 도구를 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `"Skill"`을 포함합니다. [스킬](/docs/ko/agent-sdk/skills) 참조 |

946| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - 생각 블록의 최대 토큰. 대신 `thinking` 사용 |946| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - 생각 블록의 최대 토큰. 대신 `thinking` 사용 |

947| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 확장된 생각 동작을 제어합니다. `max_thinking_tokens`보다 우선합니다 |947| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 확장된 생각 동작을 제어합니다. `max_thinking_tokens`보다 우선합니다 |

948| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | 생각 깊이를 위한 노력 수준. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |948| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | 생각 깊이를 위한 노력 수준. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level) 참조 |

949| `session_store` | [`SessionStore`](/ko/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | 세션 기록을 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있도록 합니다. [외부 저장소에 세션 유지](/ko/agent-sdk/session-storage) 참조 |949| `session_store` | [`SessionStore`](/docs/ko/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | 세션 기록을 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있도록 합니다. [외부 저장소에 세션 유지](/docs/ko/agent-sdk/session-storage) 참조 |

950| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | `session_store`에 미러링된 기록 항목을 플러시할 시기. `"batched"`는 턴당 한 번 또는 버퍼가 가득 찰 때 플러시합니다. `"eager"`는 모든 프레임 후에 백그라운드 플러시를 트리거합니다. `session_store`가 `None`일 때 무시됩니다 |950| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | `session_store`에 미러링된 기록 항목을 플러시할 시기. `"batched"`는 턴당 한 번 또는 버퍼가 가득 찰 때 플러시합니다. `"eager"`는 모든 프레임 후에 백그라운드 플러시를 트리거합니다. `session_store`가 `None`일 때 무시됩니다 |

951 951 

952<h4 id="handle-slow-or-stalled-api-responses">952<h4 id="handle-slow-or-stalled-api-responses">

966```966```

967 967 

968* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 시간 초과 (밀리초). 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.968* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 시간 초과 (밀리초). 기본값 `600000`. 주 루프 및 모든 서브에이전트에 적용됩니다.

969* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`, 최대 `15`로 제한됨. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로, 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다. 더 긴 중단을 기다려야 하는 무인 실행의 경우, `CLAUDE_CODE_RETRY_WATCHDOG=1`을 설정하여 용량 오류를 무한정 재시도합니다. 그리고 {/* min-version: 2.1.199 */}Claude Code v2.1.199 기준으로 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.969* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도. 기본값 `10`, 최대 `15`로 제한됨. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로, 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다. 더 긴 중단을 기다려야 하는 무인 실행의 경우, `CLAUDE_CODE_RETRY_WATCHDOG=1`을 설정하여 용량 오류를 무한정 재시도합니다. 그리고 Claude Code v2.1.199 기준으로 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.

970* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트의 정지 감시견. 기본값 `600000`. 각 스트림 이벤트에서 재설정됩니다. 정지 시 서브에이전트를 중단하고, 작업을 실패로 표시하고, 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.970* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트의 정지 감시견. 기본값 `600000`. 각 스트림 이벤트에서 재설정됩니다. 정지 시 서브에이전트를 중단하고, 작업을 실패로 표시하고, 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.

971* `CLAUDE_ENABLE_STREAM_WATCHDOG` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단된 요청은 정상 재시도 경로를 거칩니다.971* `CLAUDE_ENABLE_STREAM_WATCHDOG` with `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 제한됩니다. 중단된 요청은 정상 재시도 경로를 거칩니다.

972 972 

1008| `type` | 예 | 프리셋 시스템 프롬프트를 사용하려면 `"preset"`이어야 합니다 |1008| `type` | 예 | 프리셋 시스템 프롬프트를 사용하려면 `"preset"`이어야 합니다 |

1009| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |1009| `preset` | 예 | Claude Code의 시스템 프롬프트를 사용하려면 `"claude_code"`이어야 합니다 |

1010| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |1010| `append` | 아니오 | 프리셋 시스템 프롬프트에 추가할 추가 지침 |

1011| `exclude_dynamic_sections` | 아니오 | 작업 디렉토리, git 상태 및 메모리 경로와 같은 세션별 컨텍스트를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |1011| `exclude_dynamic_sections` | 아니오 | 작업 디렉토리, git 상태 및 메모리 경로와 같은 세션별 컨텍스트를 시스템 프롬프트에서 첫 사용자 메시지로 이동합니다. 사용자 및 머신 간 프롬프트 캐시 재사용을 개선합니다. [시스템 프롬프트 수정](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) 참조 |

1012 1012 

1013<h3 id="systempromptfile">1013<h3 id="systempromptfile">

1014 `SystemPromptFile`1014 `SystemPromptFile`

1015</h3>1015</h3>

1016 1016 

1017파일에서 사용자 정의 시스템 프롬프트를 로드하기 위한 구성입니다. 문자열로 전달하는 대신 파일 형식을 사용합니다. SDK는 이를 CLI [`--system-prompt-file`](/ko/cli-reference#system-prompt-flags) 플래그에 매핑합니다. 프롬프트가 큰 경우 파일 형식을 사용합니다: SDK는 문자열 `system_prompt`를 CLI 서브프로세스 argv에 전달하며, 이는 SDK가 API 요청을 보내기 전에 OS 명령줄 길이 제한의 대상입니다. Linux에서 대략 128 KB보다 긴 단일 인수는 `Argument list too long` 오류로 프로세스 생성에 실패합니다. Windows에서는 전체 명령줄이 대략 32 KB로 제한되므로 문자열 형식은 더 낮은 임계값에서 실패합니다.1017파일에서 사용자 정의 시스템 프롬프트를 로드하기 위한 구성입니다. 문자열로 전달하는 대신 파일 형식을 사용합니다. SDK는 이를 CLI [`--system-prompt-file`](/docs/ko/cli-reference#system-prompt-flags) 플래그에 매핑합니다. 프롬프트가 큰 경우 파일 형식을 사용합니다: SDK는 문자열 `system_prompt`를 CLI 서브프로세스 argv에 전달하며, 이는 SDK가 API 요청을 보내기 전에 OS 명령줄 길이 제한의 대상입니다. Linux에서 대략 128 KB보다 긴 단일 인수는 `Argument list too long` 오류로 프로세스 생성에 실패합니다. Windows에서는 전체 명령줄이 대략 32 KB로 제한되므로 문자열 형식은 더 낮은 임계값에서 실패합니다.

1018 1018 

1019```python theme={null}1019```python theme={null}

1020class SystemPromptFile(TypedDict):1020class SystemPromptFile(TypedDict):

1047 기본 동작1047 기본 동작

1048</h4>1048</h4>

1049 1049 

1050`setting_sources`가 생략되거나 `None`일 때, `query()`는 Claude Code CLI와 동일한 파일 시스템 설정을 로드합니다: 사용자, 프로젝트 및 로컬. 관리형 정책 설정은 모든 경우에 로드됩니다. 서버 관리 설정은 [적격 구성](/ko/server-managed-settings#platform-availability)에서 조직 자격증명으로 세션이 인증될 때 가져옵니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법을 참조하십시오.1050`setting_sources`가 생략되거나 `None`일 때, `query()`는 Claude Code CLI와 동일한 파일 시스템 설정을 로드합니다: 사용자, 프로젝트 및 로컬. 관리형 정책 설정은 모든 경우에 로드됩니다. 서버 관리 설정은 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 조직 자격증명으로 세션이 인증될 때 가져옵니다. [Claude Code 기능 사용](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)에서 이것이 제어하지 않는 입력 및 비활성화 방법을 참조하십시오.

1051 1051 

1052<h4 id="why-use-setting_sources">1052<h4 id="why-use-setting_sources">

1053 setting\_sources를 사용하는 이유1053 setting\_sources를 사용하는 이유

1257 1257 

1258`PermissionResult` (`PermissionResultAllow` 또는 `PermissionResultDeny`)를 반환합니다.1258`PermissionResult` (`PermissionResultAllow` 또는 `PermissionResultDeny`)를 반환합니다.

1259 1259 

1260콜백은 대화형 권한 프롬프트의 SDK 대체입니다: [권한 평가 흐름](/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 해결될 때만 호출됩니다. `allowed_tools` 항목, 설정 허용 규칙 또는 `acceptEdits` 또는 `bypassPermissions`와 같은 권한 모드로 이미 승인된 도구 호출은 이를 호출하지 않습니다. 모든 도구 호출을 제어하려면 [`PreToolUse` hook](/ko/agent-sdk/hooks)을 대신 사용합니다.1260콜백은 대화형 권한 프롬프트의 SDK 대체입니다: [권한 평가 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 해결될 때만 호출됩니다. `allowed_tools` 항목, 설정 허용 규칙 또는 `acceptEdits` 또는 `bypassPermissions`와 같은 권한 모드로 이미 승인된 도구 호출은 이를 호출하지 않습니다. 모든 도구 호출을 제어하려면 [`PreToolUse` hook](/docs/ko/agent-sdk/hooks)을 대신 사용합니다.

1261 1261 

1262`AskUserQuestion`, [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구, 및 [조직이 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구는 허용 규칙이 일치하더라도 콜백에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다.1262`AskUserQuestion`, [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구, 및 [조직이 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구는 허용 규칙이 일치하더라도 콜백에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다.

1263 1263 

1264<h3 id="toolpermissioncontext">1264<h3 id="toolpermissioncontext">

1265 `ToolPermissionContext`1265 `ToolPermissionContext`

1606]1606]

1607```1607```

1608 1608 

1609플러그인 생성 및 사용에 대한 완전한 정보는 [플러그인](/ko/agent-sdk/plugins)을 참조하십시오.1609플러그인 생성 및 사용에 대한 완전한 정보는 [플러그인](/docs/ko/agent-sdk/plugins)을 참조하십시오.

1610 1610 

1611<h2 id="message-types">1611<h2 id="message-types">

1612 메시지 타입1612 메시지 타입

1749 1749 

1750| 키 | 타입 | 설명 |1750| 키 | 타입 | 설명 |

1751| ----------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |1751| ----------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |

1752| `input_tokens` | `int` | 최상위 에이전트 루프에서 소비된 입력 토큰입니다. [서브에이전트 토큰은 포함되지 않습니다](/ko/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); 전체 트리 회계의 경우 `model_usage`를 사용하십시오. |1752| `input_tokens` | `int` | 최상위 에이전트 루프에서 소비된 입력 토큰입니다. [서브에이전트 토큰은 포함되지 않습니다](/docs/ko/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); 전체 트리 회계의 경우 `model_usage`를 사용하십시오. |

1753| `output_tokens` | `int` | 최상위 에이전트 루프에서 생성된 출력 토큰입니다. 서브에이전트 토큰은 포함되지 않습니다. |1753| `output_tokens` | `int` | 최상위 에이전트 루프에서 생성된 출력 토큰입니다. 서브에이전트 토큰은 포함되지 않습니다. |

1754| `cache_creation_input_tokens` | `int` | 새 캐시 항목을 생성하는 데 사용된 토큰입니다. |1754| `cache_creation_input_tokens` | `int` | 새 캐시 항목을 생성하는 데 사용된 토큰입니다. |

1755| `cache_read_input_tokens` | `int` | 기존 캐시 항목에서 읽은 토큰입니다. |1755| `cache_read_input_tokens` | `int` | 기존 캐시 항목에서 읽은 토큰입니다. |

1756 1756 

1757`model_usage` dict는 모델 이름을 모델별 사용량에 매핑합니다. 내부 dict 키는 camelCase를 사용합니다. 기본 CLI 프로세스에서 수정되지 않은 상태로 전달되므로 TypeScript [`ModelUsage`](/ko/agent-sdk/typescript#modelusage) 타입과 일치합니다:1757`model_usage` dict는 모델 이름을 모델별 사용량에 매핑합니다. 내부 dict 키는 camelCase를 사용합니다. 기본 CLI 프로세스에서 수정되지 않은 상태로 전달되므로 TypeScript [`ModelUsage`](/docs/ko/agent-sdk/typescript#modelusage) 타입과 일치합니다:

1758 1758 

1759| 키 | 타입 | 설명 |1759| 키 | 타입 | 설명 |

1760| -------------------------- | ------- | ---------------------------------------------------------------------------------------------- |1760| -------------------------- | ------- | ---------------------------------------------------------------------------------------------- |

1763| `cacheReadInputTokens` | `int` | 이 모델의 캐시 읽기 토큰입니다. |1763| `cacheReadInputTokens` | `int` | 이 모델의 캐시 읽기 토큰입니다. |

1764| `cacheCreationInputTokens` | `int` | 이 모델의 캐시 생성 토큰입니다. |1764| `cacheCreationInputTokens` | `int` | 이 모델의 캐시 생성 토큰입니다. |

1765| `webSearchRequests` | `int` | 이 모델이 수행한 웹 검색 요청입니다. |1765| `webSearchRequests` | `int` | 이 모델이 수행한 웹 검색 요청입니다. |

1766| `costUSD` | `float` | 이 모델의 추정 비용 (USD), 클라이언트 측 계산입니다. 청구 주의 사항은 [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking) 참조하십시오. |1766| `costUSD` | `float` | 이 모델의 추정 비용 (USD), 클라이언트 측 계산입니다. 청구 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking) 참조하십시오. |

1767| `contextWindow` | `int` | 이 모델의 컨텍스트 윈도우 크기입니다. |1767| `contextWindow` | `int` | 이 모델의 컨텍스트 윈도우 크기입니다. |

1768| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한입니다. |1768| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한입니다. |

1769 1769 

2090 Hook 타입2090 Hook 타입

2091</h2>2091</h2>

2092 2092 

2093hooks 사용에 대한 포괄적인 가이드, 예제 및 일반적인 패턴은 [Hooks 가이드](/ko/agent-sdk/hooks)를 참조하십시오.2093hooks 사용에 대한 포괄적인 가이드, 예제 및 일반적인 패턴은 [Hooks 가이드](/docs/ko/agent-sdk/hooks)를 참조하십시오.

2094 2094 

2095<h3 id="hookevent">2095<h3 id="hookevent">

2096 `HookEvent`2096 `HookEvent`

2474 `HookSpecificOutput`2474 `HookSpecificOutput`

2475</h4>2475</h4>

2476 2476 

2477hook 이벤트 이름과 이벤트 특정 필드를 포함하는 `TypedDict`입니다. 형태는 `hookEventName` 값에 따라 달라집니다. hook 이벤트별 사용 가능한 필드에 대한 전체 세부 정보는 [hooks로 실행 제어](/ko/agent-sdk/hooks#outputs)를 참조하십시오.2477hook 이벤트 이름과 이벤트 특정 필드를 포함하는 `TypedDict`입니다. 형태는 `hookEventName` 값에 따라 달라집니다. hook 이벤트별 사용 가능한 필드에 대한 전체 세부 정보는 [hooks로 실행 제어](/docs/ko/agent-sdk/hooks#outputs)를 참조하십시오.

2478 2478 

2479이벤트 특정 출력 타입의 판별된 합집합입니다. `hookEventName` 필드가 어느 필드가 유효한지 결정합니다.2479이벤트 특정 출력 타입의 판별된 합집합입니다. `hookEventName` 필드가 어느 필드가 유효한지 결정합니다.

2480 2480 

2639 2639 

2640**도구 이름:** `AskUserQuestion`2640**도구 이름:** `AskUserQuestion`

2641 2641 

2642실행 중에 사용자에게 명확히 하는 질문을 합니다. 사용 세부 정보는 [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input#handle-clarifying-questions)를 참조하십시오.2642실행 중에 사용자에게 명확히 하는 질문을 합니다. 사용 세부 정보는 [승인 및 사용자 입력 처리](/docs/ko/agent-sdk/user-input#handle-clarifying-questions)를 참조하십시오.

2643 2643 

2644**입력:**2644**입력:**

2645 2645 

2717 2717 

2718백그라운드 소스를 실행하고 각 이벤트를 Claude에 전달하여 폴링 없이 반응할 수 있도록 합니다. `command`는 스크립트를 실행하고 stdout 줄당 하나의 이벤트를 내보내며, `ws`는 WebSocket을 열고 텍스트 프레임당 하나의 이벤트를 내보냅니다. `command` 또는 `ws` 중 정확히 하나를 제공하십시오.2718백그라운드 소스를 실행하고 각 이벤트를 Claude에 전달하여 폴링 없이 반응할 수 있도록 합니다. `command`는 스크립트를 실행하고 stdout 줄당 하나의 이벤트를 내보내며, `ws`는 WebSocket을 열고 텍스트 프레임당 하나의 이벤트를 내보냅니다. `command` 또는 `ws` 중 정확히 하나를 제공하십시오.

2719 2719 

2720Monitor가 명령을 실행할 때, Bash와 동일한 권한 규칙을 따릅니다. WebSocket 감시는 별도로 승인을 요청합니다. {/* min-version: 2.1.195 */}`ws` 소스는 Claude Code v2.1.195 이상이 필요합니다. 동작 및 제공자 가용성은 [Monitor 도구 참조](/ko/tools-reference#monitor-tool)를 참조하십시오.2720Monitor가 명령을 실행할 때, Bash와 동일한 권한 규칙을 따릅니다. WebSocket 감시는 별도로 승인을 요청합니다. `ws` 소스는 Claude Code v2.1.195 이상이 필요합니다. 동작 및 제공자 가용성은 [Monitor 도구 참조](/docs/ko/tools-reference#monitor-tool)를 참조하십시오.

2721 2721 

2722**입력:**2722**입력:**

2723 2723 

2995**도구 이름:** `TodoWrite`2995**도구 이름:** `TodoWrite`

2996 2996 

2997<Note>2997<Note>

2998 Claude Code v2.1.142부터 `TodoWrite`는 기본적으로 비활성화되어 있습니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하는 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌리십시오.2998 Claude Code v2.1.142부터 `TodoWrite`는 기본적으로 비활성화되어 있습니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하는 방법은 [작업 도구로 마이그레이션](/docs/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌리십시오.

2999</Note>2999</Note>

3000 3000 

3001**입력:**3001**입력:**

3699 `SandboxNetworkConfig`3699 `SandboxNetworkConfig`

3700</h3>3700</h3>

3701 3701 

3702샌드박스 모드를 위한 네트워크 특정 구성입니다. 이러한 설정은 부모 [`SandboxSettings`](#sandboxsettings)에서 `enabled`가 `True`일 때 샌드박스된 Bash 명령에 적용됩니다. 이들은 [권한 규칙](/ko/permissions#webfetch)을 대신 사용하는 WebFetch 도구를 제한하지 않습니다.3702샌드박스 모드를 위한 네트워크 특정 구성입니다. 이러한 설정은 부모 [`SandboxSettings`](#sandboxsettings)에서 `enabled`가 `True`일 때 샌드박스된 Bash 명령에 적용됩니다. 이들은 [권한 규칙](/docs/ko/permissions#webfetch)을 대신 사용하는 WebFetch 도구를 제한하지 않습니다.

3703 3703 

3704```python theme={null}3704```python theme={null}

3705class SandboxNetworkConfig(TypedDict, total=False):3705class SandboxNetworkConfig(TypedDict, total=False):

3727| `socksProxyPort` | `int` | `None` | 네트워크 요청을 위한 SOCKS 프록시 포트 |3727| `socksProxyPort` | `int` | `None` | 네트워크 요청을 위한 SOCKS 프록시 포트 |

3728 3728 

3729<Note>3729<Note>

3730 기본 제공 샌드박스 프록시는 요청된 호스트명을 기반으로 네트워크 허용 목록을 적용하며 TLS 트래픽을 종료하거나 검사하지 않으므로, [도메인 프론팅](https://en.wikipedia.org/wiki/Domain_fronting)과 같은 기술이 이를 우회할 수 있습니다. 자세한 내용은 [샌드박싱 보안 제한 사항](/ko/sandboxing#security-limitations)을 참조하고, TLS 종료 프록시 구성은 [안전한 배포](/ko/agent-sdk/secure-deployment#traffic-forwarding)를 참조하십시오.3730 기본 제공 샌드박스 프록시는 요청된 호스트명을 기반으로 네트워크 허용 목록을 적용하며 TLS 트래픽을 종료하거나 검사하지 않으므로, [도메인 프론팅](https://en.wikipedia.org/wiki/Domain_fronting)과 같은 기술이 이를 우회할 수 있습니다. 자세한 내용은 [샌드박싱 보안 제한 사항](/docs/ko/sandboxing#security-limitations)을 참조하고, TLS 종료 프록시 구성은 [안전한 배포](/docs/ko/agent-sdk/secure-deployment#traffic-forwarding)를 참조하십시오.

3731</Note>3731</Note>

3732 3732 

3733<h3 id="sandboxignoreviolations">3733<h3 id="sandboxignoreviolations">

3831 참고 항목3831 참고 항목

3832</h2>3832</h2>

3833 3833 

3834* [SDK 개요](/ko/agent-sdk/overview) - 일반 SDK 개념3834* [SDK 개요](/docs/ko/agent-sdk/overview) - 일반 SDK 개념

3835* [TypeScript SDK 참조](/ko/agent-sdk/typescript) - TypeScript SDK 문서3835* [TypeScript SDK 참조](/docs/ko/agent-sdk/typescript) - TypeScript SDK 문서

3836* [CLI 참조](/ko/cli-reference) - 명령줄 인터페이스3836* [CLI 참조](/docs/ko/cli-reference) - 명령줄 인터페이스

3837* [일반적인 워크플로우](/ko/common-workflows) - 단계별 가이드3837* [일반적인 워크플로우](/docs/ko/common-workflows) - 단계별 가이드

17 17 

18서브에이전트를 세 가지 방법으로 생성할 수 있습니다.18서브에이전트를 세 가지 방법으로 생성할 수 있습니다.

19 19 

20* **프로그래밍 방식**: `query()` 옵션에서 `agents` 매개변수 사용. [TypeScript](/ko/agent-sdk/typescript#agentdefinition) 및 [Python](/ko/agent-sdk/python#agentdefinition) 참조 확인20* **프로그래밍 방식**: `query()` 옵션에서 `agents` 매개변수 사용. [TypeScript](/docs/ko/agent-sdk/typescript#agentdefinition) 및 [Python](/docs/ko/agent-sdk/python#agentdefinition) 참조 확인

21* **파일 시스템 기반**: `.claude/agents/` 디렉토리에 마크다운 파일로 에이전트 정의. [서브에이전트를 파일로 정의](/ko/sub-agents) 참조21* **파일 시스템 기반**: `.claude/agents/` 디렉토리에 마크다운 파일로 에이전트 정의. [서브에이전트를 파일로 정의](/docs/ko/sub-agents) 참조

22* **기본 제공 범용**: Claude는 언제든지 Agent 도구를 통해 기본 제공 `general-purpose` 서브에이전트를 호출할 수 있습니다.22* **기본 제공 범용**: Claude는 언제든지 Agent 도구를 통해 기본 제공 `general-purpose` 서브에이전트를 호출할 수 있습니다.

23 23 

24이 가이드는 SDK 애플리케이션에 권장되는 프로그래밍 방식에 중점을 둡니다.24이 가이드는 SDK 애플리케이션에 권장되는 프로그래밍 방식에 중점을 둡니다.

197| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | 아니오 | 이 에이전트의 추론 노력 수준 |197| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | 아니오 | 이 에이전트의 추론 노력 수준 |

198| `permissionMode` | `PermissionMode` | 아니오 | 이 에이전트 내의 도구 실행을 위한 권한 모드 |198| `permissionMode` | `PermissionMode` | 아니오 | 이 에이전트 내의 도구 실행을 위한 권한 모드 |

199 199 

200Python SDK에서 `disallowedTools` 및 `mcpServers`와 같은 여러 단어로 된 필드 이름은 Python의 snake\_case 규칙을 따르지 않고 와이어 형식과 일치하도록 camelCase를 유지합니다. 자세한 내용은 [`AgentDefinition` 참조](/ko/agent-sdk/python#agentdefinition)를 참조하세요.200Python SDK에서 `disallowedTools` 및 `mcpServers`와 같은 여러 단어로 된 필드 이름은 Python의 snake\_case 규칙을 따르지 않고 와이어 형식과 일치하도록 camelCase를 유지합니다. 자세한 내용은 [`AgentDefinition` 참조](/docs/ko/agent-sdk/python#agentdefinition)를 참조하세요.

201 201 

202Claude Code v2.1.198에서 두 가지 서브에이전트 동작이 변경되었습니다:202Claude Code v2.1.198에서 두 가지 서브에이전트 동작이 변경되었습니다:

203 203 

204* 서브에이전트는 기본적으로 백그라운드에서 실행됩니다. [`run_in_background`](/ko/agent-sdk/typescript) 입력을 생략하는 Agent 도구 호출은 백그라운드 서브에이전트를 시작하고, Claude는 계속하기 전에 결과가 필요할 때 `run_in_background: false`를 설정합니다. v2.1.198 이전에는 `run_in_background`를 생략하면 서브에이전트가 동기적으로 실행되었습니다. 특정 에이전트에 대해 Claude가 요청하는 것과 관계없이 백그라운드 실행을 강제하려면 `background` 필드를 `true`로 설정합니다.204* 서브에이전트는 기본적으로 백그라운드에서 실행됩니다. [`run_in_background`](/docs/ko/agent-sdk/typescript) 입력을 생략하는 Agent 도구 호출은 백그라운드 서브에이전트를 시작하고, Claude는 계속하기 전에 결과가 필요할 때 `run_in_background: false`를 설정합니다. v2.1.198 이전에는 `run_in_background`를 생략하면 서브에이전트가 동기적으로 실행되었습니다. 특정 에이전트에 대해 Claude가 요청하는 것과 관계없이 백그라운드 실행을 강제하려면 `background` 필드를 `true`로 설정합니다.

205* 서브에이전트는 메인 세션의 확장 사고 구성을 상속합니다. 이전 버전에서는 메인 세션의 설정과 관계없이 서브에이전트 내에서 확장 사고가 비활성화됩니다.205* 서브에이전트는 메인 세션의 확장 사고 구성을 상속합니다. 이전 버전에서는 메인 세션의 설정과 관계없이 서브에이전트 내에서 확장 사고가 비활성화됩니다.

206 206 

207<Note>207<Note>

208 {/* min-version: 2.1.172 */}Claude Code v2.1.172부터 서브에이전트는 자신의 서브에이전트를 생성할 수 있습니다. 메인 에이전트 아래 5단계 깊이의 서브에이전트는 포그라운드 또는 백그라운드에서 실행되는지 여부와 관계없이 추가 서브에이전트를 생성할 수 없습니다. 서브에이전트가 다른 서브에이전트를 생성하지 못하도록 하려면 `tools` 배열에서 `Agent`를 생략하거나 `disallowedTools`에 추가합니다. 전체 깊이 규칙은 [중첩된 서브에이전트](/ko/sub-agents#spawn-nested-subagents)를 참조하세요.208 Claude Code v2.1.172부터 서브에이전트는 자신의 서브에이전트를 생성할 수 있습니다. 메인 에이전트 아래 5단계 깊이의 서브에이전트는 포그라운드 또는 백그라운드에서 실행되는지 여부와 관계없이 추가 서브에이전트를 생성할 수 없습니다. 서브에이전트가 다른 서브에이전트를 생성하지 못하도록 하려면 `tools` 배열에서 `Agent`를 생략하거나 `disallowedTools`에 추가합니다. 전체 깊이 규칙은 [중첩된 서브에이전트](/docs/ko/sub-agents#spawn-nested-subagents)를 참조하세요.

209</Note>209</Note>

210 210 

211<h3 id="filesystem-based-definition-alternative">211<h3 id="filesystem-based-definition-alternative">

212 파일 시스템 기반 정의 (대안)212 파일 시스템 기반 정의 (대안)

213</h3>213</h3>

214 214 

215`.claude/agents/` 디렉토리에 마크다운 파일로 서브에이전트를 정의할 수도 있습니다. 이 방식에 대한 자세한 내용은 [Claude Code 서브에이전트 문서](/ko/sub-agents)를 참조하세요. 프로그래밍 방식으로 정의된 에이전트는 같은 이름의 파일 시스템 기반 에이전트보다 우선합니다.215`.claude/agents/` 디렉토리에 마크다운 파일로 서브에이전트를 정의할 수도 있습니다. 이 방식에 대한 자세한 내용은 [Claude Code 서브에이전트 문서](/docs/ko/sub-agents)를 참조하세요. 프로그래밍 방식으로 정의된 에이전트는 같은 이름의 파일 시스템 기반 에이전트보다 우선합니다.

216 216 

217<Note>217<Note>

218 사용자 정의 서브에이전트를 정의하지 않더라도, Claude는 기본 제공 `general-purpose` 서브에이전트를 생성할 수 있습니다. 이는 특화된 에이전트를 만들지 않고도 연구 또는 탐색 작업을 위임하는 데 유용합니다. `allowedTools`에 `Agent`를 포함하여 권한 프롬프트 없이 이러한 호출을 자동으로 승인합니다.218 사용자 정의 서브에이전트를 정의하지 않더라도, Claude는 기본 제공 `general-purpose` 서브에이전트를 생성할 수 있습니다. 이는 특화된 에이전트를 만들지 않고도 연구 또는 탐색 작업을 위임하는 데 유용합니다. `allowedTools`에 `Agent`를 포함하여 권한 프롬프트 없이 이러한 호출을 자동으로 승인합니다.

224 224 

225서브에이전트의 컨텍스트 윈도우는 새로 시작되지만(부모 대화 없음) 비어 있지 않습니다. 부모에서 서브에이전트로의 유일한 채널은 Agent 도구의 프롬프트 문자열이므로, 서브에이전트가 필요한 파일 경로, 오류 메시지 또는 결정을 해당 프롬프트에 직접 포함하세요.225서브에이전트의 컨텍스트 윈도우는 새로 시작되지만(부모 대화 없음) 비어 있지 않습니다. 부모에서 서브에이전트로의 유일한 채널은 Agent 도구의 프롬프트 문자열이므로, 서브에이전트가 필요한 파일 경로, 오류 메시지 또는 결정을 해당 프롬프트에 직접 포함하세요.

226 226 

227{/* min-version: 2.1.206 */}[`SendMessage`](/ko/tools-reference) 도구를 가진 서브에이전트는 세션에서 실행 중인 다른 명명된 에이전트 목록으로 시작하므로, 메시지를 보낼 수 있는 이름을 알 수 있습니다. Claude Code는 서브에이전트의 첫 번째 턴에 자동으로 목록을 추가합니다. [포크](/ko/sub-agents#fork-the-current-conversation)는 부모 대화를 상속하므로 목록을 받지 않습니다. 이 목록은 Claude Code v2.1.206 이상이 필요합니다.227[`SendMessage`](/docs/ko/tools-reference) 도구를 가진 서브에이전트는 세션에서 실행 중인 다른 명명된 에이전트 목록으로 시작하므로, 메시지를 보낼 수 있는 이름을 알 수 있습니다. Claude Code는 서브에이전트의 첫 번째 턴에 자동으로 목록을 추가합니다. [포크](/docs/ko/sub-agents#fork-the-current-conversation)는 부모 대화를 상속하므로 목록을 받지 않습니다. 이 목록은 Claude Code v2.1.206 이상이 필요합니다.

228 228 

229| 서브에이전트가 받는 것 | 서브에이전트가 받지 않는 것 |229| 서브에이전트가 받는 것 | 서브에이전트가 받지 않는 것 |

230| :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------- |230| :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------- |

231| 자신의 시스템 프롬프트(`AgentDefinition.prompt`)와 Agent 도구의 프롬프트 | 부모의 대화 기록 또는 도구 결과 |231| 자신의 시스템 프롬프트(`AgentDefinition.prompt`)와 Agent 도구의 프롬프트 | 부모의 대화 기록 또는 도구 결과 |

232| 프로젝트 CLAUDE.md ([`settingSources`](/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 통해 로드됨) | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |232| 프로젝트 CLAUDE.md ([`settingSources`](/docs/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 통해 로드됨) | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |

233| 도구 정의 (부모에서 상속되거나 `tools`의 부분 집합) | 부모의 시스템 프롬프트 |233| 도구 정의 (부모에서 상속되거나 `tools`의 부분 집합) | 부모의 시스템 프롬프트 |

234 234 

235<Note>235<Note>

236 부모는 서브에이전트의 최종 메시지를 Agent 도구 결과로 그대로 받지만, 자신의 응답에서 요약할 수 있습니다. 서브에이전트 출력을 사용자 대면 응답에서 그대로 유지하려면, 메인 `query()` 호출에 전달하는 프롬프트 또는 `systemPrompt` 옵션에 그렇게 하도록 지시하는 지침을 포함하세요.236 부모는 서브에이전트의 최종 메시지를 Agent 도구 결과로 그대로 받지만, 자신의 응답에서 요약할 수 있습니다. 서브에이전트 출력을 사용자 대면 응답에서 그대로 유지하려면, 메인 `query()` 호출에 전달하는 프롬프트 또는 `systemPrompt` 옵션에 그렇게 하도록 지시하는 지침을 포함하세요.

237</Note>237</Note>

238 238 

239속도 제한과 같이 서브에이전트를 조기에 종료하는 API 오류는 절대 결과로 전달되지 않습니다. 속도 제한, 과부하 또는 서버 오류가 이미 텍스트 출력을 생성한 포그라운드 서브에이전트를 중단하는 경우, Agent 도구는 서브에이전트가 완료되지 않았다는 메모와 함께 해당 부분 출력을 반환합니다. 아무것도 생성하지 않았거나 텍스트 없이 도구 호출만 있었던 서브에이전트는 오류 메시지 `Agent terminated early due to an API error`와 함께 실패하며, 그 뒤에 오류 세부 정보가 따릅니다. [서브에이전트의 API 오류](/ko/sub-agents#api-errors-in-subagents)에서 포그라운드 및 백그라운드 동작을 참조하세요.239속도 제한과 같이 서브에이전트를 조기에 종료하는 API 오류는 절대 결과로 전달되지 않습니다. 속도 제한, 과부하 또는 서버 오류가 이미 텍스트 출력을 생성한 포그라운드 서브에이전트를 중단하는 경우, Agent 도구는 서브에이전트가 완료되지 않았다는 메모와 함께 해당 부분 출력을 반환합니다. 아무것도 생성하지 않았거나 텍스트 없이 도구 호출만 있었던 서브에이전트는 오류 메시지 `Agent terminated early due to an API error`와 함께 실패하며, 그 뒤에 오류 세부 정보가 따릅니다. [서브에이전트의 API 오류](/docs/ko/sub-agents#api-errors-in-subagents)에서 포그라운드 및 백그라운드 동작을 참조하세요.

240 240 

241이 부분 출력 처리는 Claude Code v2.1.199 이상이 필요합니다. v2.1.199에서는 속도 제한, 과부하 또는 서버 오류로 인해 도구 호출만 있는 형태가 중단 메모만 포함된 빈 부분 결과로 남겨졌습니다.241이 부분 출력 처리는 Claude Code v2.1.199 이상이 필요합니다. v2.1.199에서는 속도 제한, 과부하 또는 서버 오류로 인해 도구 호출만 있는 형태가 중단 메모만 포함된 빈 부분 결과로 남겨졌습니다.

242 242 

441 441 

442서브에이전트를 재개하여 중단한 지점에서 계속할 수 있습니다. 재개된 서브에이전트는 이전의 모든 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다.442서브에이전트를 재개하여 중단한 지점에서 계속할 수 있습니다. 재개된 서브에이전트는 이전의 모든 도구 호출, 결과 및 추론을 포함한 전체 대화 기록을 유지합니다.

443 443 

444서브에이전트가 완료되면, Agent 도구 결과에는 `agentId: <id>`를 포함하는 텍스트 블록이 포함됩니다. 기본 제공 [`Explore` 및 `Plan` 에이전트](/ko/sub-agents#built-in-subagents)는 일회성이며 `agentId`를 반환하지 않으므로, 재개가 필요한 경우 사용자 정의 에이전트 또는 `general-purpose`를 사용하세요. 서브에이전트를 프로그래밍 방식으로 재개하려면:444서브에이전트가 완료되면, Agent 도구 결과에는 `agentId: <id>`를 포함하는 텍스트 블록이 포함됩니다. 기본 제공 [`Explore` 및 `Plan` 에이전트](/docs/ko/sub-agents#built-in-subagents)는 일회성이며 `agentId`를 반환하지 않으므로, 재개가 필요한 경우 사용자 정의 에이전트 또는 `general-purpose`를 사용하세요. 서브에이전트를 프로그래밍 방식으로 재개하려면:

445 445 

4461. **세션 ID 캡처**: 첫 번째 쿼리 중에 메시지에서 `session_id` 추출4461. **세션 ID 캡처**: 첫 번째 쿼리 중에 메시지에서 `session_id` 추출

4472. **에이전트 ID 추출**: Agent 도구 결과 텍스트에서 `agentId` 파싱4472. **에이전트 ID 추출**: Agent 도구 결과 텍스트에서 `agentId` 파싱

661 동적 워크플로우로 확장661 동적 워크플로우로 확장

662</h2>662</h2>

663 663 

664서브에이전트는 턴당 몇 가지 위임된 작업에 적합합니다. 수십 개에서 수백 개의 에이전트를 조정하는 실행의 경우, `Workflow` 도구를 사용하세요. 이는 오케스트레이션을 대화 컨텍스트 외부에서 런타임이 실행하는 스크립트로 이동합니다. 워크플로우가 턴별 서브에이전트 위임과 어떻게 다른지는 [동적 워크플로우](/ko/workflows)를 참조하세요.664서브에이전트는 턴당 몇 가지 위임된 작업에 적합합니다. 수십 개에서 수백 개의 에이전트를 조정하는 실행의 경우, `Workflow` 도구를 사용하세요. 이는 오케스트레이션을 대화 컨텍스트 외부에서 런타임이 실행하는 스크립트로 이동합니다. 워크플로우가 턴별 서브에이전트 위임과 어떻게 다른지는 [동적 워크플로우](/docs/ko/workflows)를 참조하세요.

665 665 

666`Workflow` 도구는 TypeScript Agent SDK v0.3.149 이상에서 사용 가능합니다. `allowedTools`에 `Workflow`를 포함하여 워크플로우 실행을 자동 승인합니다. 도구 입력 및 출력 스키마는 [TypeScript 참조](/ko/agent-sdk/typescript#workflow)에 나열되어 있습니다.666`Workflow` 도구는 TypeScript Agent SDK v0.3.149 이상에서 사용 가능합니다. `allowedTools`에 `Workflow`를 포함하여 워크플로우 실행을 자동 승인합니다. 도구 입력 및 출력 스키마는 [TypeScript 참조](/docs/ko/agent-sdk/typescript#workflow)에 나열되어 있습니다.

667 667 

668<h2 id="troubleshooting">668<h2 id="troubleshooting">

669 문제 해결669 문제 해결

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

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

692 692 

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

694 694 

695<h3 id="long-prompt-failures-on-windows">695<h3 id="long-prompt-failures-on-windows">

696 Windows에서 긴 프롬프트 실패696 Windows에서 긴 프롬프트 실패

702 관련 문서702 관련 문서

703</h2>703</h2>

704 704 

705* [Claude Code 서브에이전트](/ko/sub-agents): 파일 시스템 기반 정의를 포함한 포괄적인 서브에이전트 문서705* [Claude Code 서브에이전트](/docs/ko/sub-agents): 파일 시스템 기반 정의를 포함한 포괄적인 서브에이전트 문서

706* [동적 워크플로우](/ko/workflows): 한 대화에 너무 큰 작업을 위해 스크립트에서 많은 서브에이전트를 오케스트레이션합니다706* [동적 워크플로우](/docs/ko/workflows): 한 대화에 너무 큰 작업을 위해 스크립트에서 많은 서브에이전트를 오케스트레이션합니다

707* [SDK 개요](/ko/agent-sdk/overview): Claude Agent SDK 시작하기707* [SDK 개요](/docs/ko/agent-sdk/overview): Claude Agent SDK 시작하기

40 예제40 예제

41</h2>41</h2>

42 42 

43이 예제들을 실행하기 전에 [빠른 시작](/ko/agent-sdk/quickstart)을 따라 Claude Agent SDK를 설치하십시오.43이 예제들을 실행하기 전에 [빠른 시작](/docs/ko/agent-sdk/quickstart)을 따라 Claude Agent SDK를 설치하십시오.

44 44 

45각 예제는 에이전트가 완료될 때까지 실행되고 최종 결과 메시지를 생성합니다. 세션이 먼저 턴 제한에 도달하면 해당 결과 메시지는 `error_max_turns` 서브타입을 가집니다. 해당 종료를 감지하려면 `subtype`을 확인하십시오.45각 예제는 에이전트가 완료될 때까지 실행되고 최종 결과 메시지를 생성합니다. 세션이 먼저 턴 제한에 도달하면 해당 결과 메시지는 `error_max_turns` 서브타입을 가집니다. 해당 종료를 감지하려면 `subtype`을 확인하십시오.

46 46 

47이 예제들은 단일 `query()` 호출을 사용합니다. `error_max_turns` 결과를 생성한 후 `query()`는 `Reached maximum number of turns`를 포함하는 오류를 발생시킵니다. 각 예제는 이것이 발생할 때 깔끔하게 종료하기 위해 루프를 try 블록으로 래핑합니다.47이 예제들은 단일 `query()` 호출을 사용합니다. `error_max_turns` 결과를 생성한 후 `query()`는 `Reached maximum number of turns`를 포함하는 오류를 발생시킵니다. 각 예제는 이것이 발생할 때 깔끔하게 종료하기 위해 루프를 try 블록으로 래핑합니다.

48 48 

49결과 서브타입에 대해서는 [결과 처리](/ko/agent-sdk/agent-loop#handle-the-result)를 참조하십시오.49결과 서브타입에 대해서는 [결과 처리](/docs/ko/agent-sdk/agent-loop#handle-the-result)를 참조하십시오.

50 50 

51<h3 id="monitoring-todo-changes">51<h3 id="monitoring-todo-changes">

52 할일 변경 모니터링52 할일 변경 모니터링

253 Task 도구로 마이그레이션253 Task 도구로 마이그레이션

254</h2>254</h2>

255 255 

256Task 도구는 단일 `TodoWrite` 호출을 각 새 항목에 대한 `TaskCreate`와 각 상태 변경에 대한 `TaskUpdate`로 분할하며, `TaskList`와 `TaskGet`은 모델이 현재 목록을 다시 읽을 수 있도록 사용 가능합니다. 모니터링 코드는 여전히 어시스턴트 스트림의 `tool_use` 블록을 검사하지만, 모든 호출에서 전체 목록을 바꾸는 대신 작업 ID로 키가 지정된 맵을 유지합니다. {/* min-version: 2.1.142 */}Task 도구는 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 기본값이므로 `options.env` 변경이 필요하지 않습니다.256Task 도구는 단일 `TodoWrite` 호출을 각 새 항목에 대한 `TaskCreate`와 각 상태 변경에 대한 `TaskUpdate`로 분할하며, `TaskList`와 `TaskGet`은 모델이 현재 목록을 다시 읽을 수 있도록 사용 가능합니다. 모니터링 코드는 여전히 어시스턴트 스트림의 `tool_use` 블록을 검사하지만, 모든 호출에서 전체 목록을 바꾸는 대신 작업 ID로 키가 지정된 맵을 유지합니다. Task 도구는 TypeScript Agent SDK 0.3.142 및 Claude Code v2.1.142부터 기본값이므로 `options.env` 변경이 필요하지 않습니다.

257 257 

258| `TodoWrite` 사용 | Task 도구 사용 |258| `TodoWrite` 사용 | Task 도구 사용 |

259| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |259| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

338 관련 문서338 관련 문서

339</h2>339</h2>

340 340 

341* [TypeScript SDK 참고](/ko/agent-sdk/typescript)341* [TypeScript SDK 참고](/docs/ko/agent-sdk/typescript)

342* [Python SDK 참고](/ko/agent-sdk/python)342* [Python SDK 참고](/docs/ko/agent-sdk/python)

343* [스트리밍 vs 단일 모드](/ko/agent-sdk/streaming-vs-single-mode)343* [스트리밍 vs 단일 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)

344* [사용자 정의 도구](/ko/agent-sdk/custom-tools)344* [사용자 정의 도구](/docs/ko/agent-sdk/custom-tools)

6 6 

7> TypeScript Agent SDK의 완전한 API 참조로, 모든 함수, 타입 및 인터페이스를 포함합니다.7> TypeScript Agent SDK의 완전한 API 참조로, 모든 함수, 타입 및 인터페이스를 포함합니다.

8 8 

9<script src="/components/typescript-sdk-type-links.js" defer />9<script src="/docs/components/typescript-sdk-type-links.js" defer />

10 10 

11<h2 id="installation">11<h2 id="installation">

12 설치12 설치

296</h4>296</h4>

297 297 

298| 속성 | 타입 | 설명 |298| 속성 | 타입 | 설명 |

299| :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |299| :------------------- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

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

303| `message` | `unknown` | 트랜스크립트의 원본 메시지 페이로드 |303| `message` | `unknown` | 트랜스크립트의 원본 메시지 페이로드 |

304| `parent_tool_use_id` | `string \| null` | 서브에이전트 메시지의 경우 생성 `Agent` 도구 호출의 `tool_use_id`입니다. 메인 세션 메시지 및 이전 세션의 경우 `null` |304| `parent_tool_use_id` | `string \| null` | 서브에이전트 메시지의 경우 생성 `Agent` 도구 호출의 `tool_use_id`입니다. 메인 세션 메시지 및 이전 세션의 경우 `null` |

305| `parent_agent_id` | `string \| null` | [중첩된 서브에이전트](/ko/sub-agents#spawn-nested-subagents)의 메시지의 경우 이를 생성한 서브에이전트의 `agentId`입니다. 메인 세션 메시지, 최상위 서브에이전트의 메시지 및 이전 세션의 경우 `null`입니다. {/* min-version: 2.1.202 */}Claude Code v2.1.202 이상 필요 |305| `parent_agent_id` | `string \| null` | [중첩된 서브에이전트](/docs/ko/sub-agents#spawn-nested-subagents)의 메시지의 경우 이를 생성한 서브에이전트의 `agentId`입니다. 메인 세션 메시지, 최상위 서브에이전트의 메시지 및 이전 세션의 경우 `null`입니다. Claude Code v2.1.202 이상 필요 |

306 306 

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

308 예제308 예제

474| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 프로그래밍 방식으로 서브에이전트 정의 |474| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 프로그래밍 방식으로 서브에이전트 정의 |

475| `agentProgressSummaries` | `boolean` | `false` | `true`일 때 서브에이전트에 대한 한 줄 진행 요약을 생성하고 `summary` 필드를 통해 [`task_progress`](#sdktaskprogressmessage) 이벤트에서 전달합니다. 포그라운드 및 백그라운드 서브에이전트에 적용됩니다 |475| `agentProgressSummaries` | `boolean` | `false` | `true`일 때 서브에이전트에 대한 한 줄 진행 요약을 생성하고 `summary` 필드를 통해 [`task_progress`](#sdktaskprogressmessage) 이벤트에서 전달합니다. 포그라운드 및 백그라운드 서브에이전트에 적용됩니다 |

476| `allowDangerouslySkipPermissions` | `boolean` | `false` | 권한 건너뛰기를 활성화합니다. `permissionMode: 'bypassPermissions'`를 사용할 때 필수입니다 |476| `allowDangerouslySkipPermissions` | `boolean` | `false` | 권한 건너뛰기를 활성화합니다. `permissionMode: 'bypassPermissions'`를 사용할 때 필수입니다 |

477| `allowedTools` | `string[]` | `[]` | 프롬프트 없이 자동 승인할 도구입니다. 이것은 Claude를 이 도구들로만 제한하지 않습니다. 나열되지 않은 도구는 `permissionMode` 및 `canUseTool`로 넘어갑니다. `disallowedTools`를 사용하여 도구를 차단합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |477| `allowedTools` | `string[]` | `[]` | 프롬프트 없이 자동 승인할 도구입니다. 이것은 Claude를 이 도구들로만 제한하지 않습니다. 나열되지 않은 도구는 `permissionMode` 및 `canUseTool`로 넘어갑니다. `disallowedTools`를 사용하여 도구를 차단합니다. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

478| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 베타 기능 활성화 |478| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 베타 기능 활성화 |

479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 사용자 정의 권한 함수로, [권한 흐름](/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowedTools`, 허용 규칙 또는 `permissionMode`에 의해 자동 승인된 호출에 대해서는 호출되지 않습니다. `AskUserQuestion`, 커넥터 도구 [조직이 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools) 및 [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치하더라도 이에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다. 자세한 내용은 [`CanUseTool`](#canusetool) 참조 |479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 사용자 정의 권한 함수로, [권한 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 넘어갈 때만 호출됩니다. `allowedTools`, 허용 규칙 또는 `permissionMode`에 의해 자동 승인된 호출에 대해서는 호출되지 않습니다. `AskUserQuestion`, 커넥터 도구 [조직이 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools) 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치하더라도 이에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다. 자세한 내용은 [`CanUseTool`](#canusetool) 참조 |

480| `continue` | `boolean` | `false` | 가장 최근 대화 계속 |480| `continue` | `boolean` | `false` | 가장 최근 대화 계속 |

481| `cwd` | `string` | `process.cwd()` | 현재 작업 디렉토리 |481| `cwd` | `string` | `process.cwd()` | 현재 작업 디렉토리 |

482| `debug` | `boolean` | `false` | Claude Code 프로세스에 대한 디버그 모드 활성화 |482| `debug` | `boolean` | `false` | Claude Code 프로세스에 대한 디버그 모드 활성화 |

483| `debugFile` | `string` | `undefined` | 특정 파일 경로에 디버그 로그를 작성합니다. 암묵적으로 디버그 모드를 활성화합니다 |483| `debugFile` | `string` | `undefined` | 특정 파일 경로에 디버그 로그를 작성합니다. 암묵적으로 디버그 모드를 활성화합니다 |

484| `disallowedTools` | `string[]` | `[]` | 거부할 도구입니다. `Bash`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [권한](/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |484| `disallowedTools` | `string[]` | `[]` | 거부할 도구입니다. `Bash`와 같은 단순 이름은 Claude의 컨텍스트에서 도구를 제거합니다. `Bash(rm *)`와 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 `bypassPermissions`를 포함한 모든 권한 모드에서 일치하는 호출을 거부합니다. [권한](/docs/ko/agent-sdk/permissions#allow-and-deny-rules) 참조 |

485| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | 모델 기본값 | Claude가 응답에 투입하는 노력의 양을 제어합니다. 적응형 사고와 함께 작동하여 사고 깊이를 안내합니다. [노력 수준 조정](/ko/model-config#adjust-effort-level) 참조 |485| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | 모델 기본값 | Claude가 응답에 투입하는 노력의 양을 제어합니다. 적응형 사고와 함께 작동하여 사고 깊이를 안내합니다. [노력 수준 조정](/docs/ko/model-config#adjust-effort-level) 참조 |

486| `enableFileCheckpointing` | `boolean` | `false` | 되감기를 위한 파일 변경 추적을 활성화합니다. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |486| `enableFileCheckpointing` | `boolean` | `false` | 되감기를 위한 파일 변경 추적을 활성화합니다. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |

487| `env` | `Record<string, string \| undefined>` | `process.env` | 환경 변수입니다. 설정하면 이는 `process.env`와 병합하는 대신 서브프로세스 환경을 대체하므로 `PATH`와 같은 상속된 변수를 유지하려면 `{ ...process.env, YOUR_VAR: 'value' }`를 전달합니다. [느린 또는 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses)에서 이 패턴의 예제를 참조하고, 기본 CLI가 읽는 변수는 [환경 변수](/ko/env-vars)를 참조하세요. User-Agent 헤더에서 앱을 식별하려면 `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정합니다 |487| `env` | `Record<string, string \| undefined>` | `process.env` | 환경 변수입니다. 설정하면 이는 `process.env`와 병합하는 대신 서브프로세스 환경을 대체하므로 `PATH`와 같은 상속된 변수를 유지하려면 `{ ...process.env, YOUR_VAR: 'value' }`를 전달합니다. [느린 또는 정지된 API 응답 처리](#handle-slow-or-stalled-api-responses)에서 이 패턴의 예제를 참조하고, 기본 CLI가 읽는 변수는 [환경 변수](/docs/ko/env-vars)를 참조하세요. User-Agent 헤더에서 앱을 식별하려면 `CLAUDE_AGENT_SDK_CLIENT_APP`을 설정합니다 |

488| `executable` | `'bun' \| 'deno' \| 'node'` | 자동 감지 | 사용할 JavaScript 런타임 |488| `executable` | `'bun' \| 'deno' \| 'node'` | 자동 감지 | 사용할 JavaScript 런타임 |

489| `executableArgs` | `string[]` | `[]` | 실행 파일에 전달할 인수 |489| `executableArgs` | `string[]` | `[]` | 실행 파일에 전달할 인수 |

490| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수 |490| `extraArgs` | `Record<string, string \| null>` | `{}` | 추가 인수 |

496| `includePartialMessages` | `boolean` | `false` | 부분 메시지 이벤트 포함 |496| `includePartialMessages` | `boolean` | `false` | 부분 메시지 이벤트 포함 |

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

498| `managedSettings` | `Settings` | `undefined` | 생성 부모 프로세스에서 제공하는 정책 계층 설정입니다. 머신에 IT 제어 관리 설정 계층이 이미 있으면 삭제되며, 해당 관리자가 `parentSettingsBehavior: 'merge'`로 옵트인하지 않는 한 삭제됩니다. 제한적 전용 키로 필터링됩니다 |498| `managedSettings` | `Settings` | `undefined` | 생성 부모 프로세스에서 제공하는 정책 계층 설정입니다. 머신에 IT 제어 관리 설정 계층이 이미 있으면 삭제되며, 해당 관리자가 `parentSettingsBehavior: 'merge'`로 옵트인하지 않는 한 삭제됩니다. 제한적 전용 키로 필터링됩니다 |

499| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리를 중지합니다. `total_cost_usd`와 동일한 추정과 비교됩니다. [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking) 참조 |499| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리를 중지합니다. `total_cost_usd`와 동일한 추정과 비교됩니다. [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking) 참조 |

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

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

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

503| `model` | `string` | CLI의 기본값 | Claude 모델 별칭 또는 전체 모델 이름입니다. [허용되는 값 및 공급자별 ID](/ko/model-config#available-models) 참조 |503| `model` | `string` | CLI의 기본값 | Claude 모델 별칭 또는 전체 모델 이름입니다. [허용되는 값 및 공급자별 ID](/docs/ko/model-config#available-models) 참조 |

504| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP 유도 요청을 처리하기 위한 콜백입니다. MCP 서버가 사용자 입력을 요청하고 훅이 먼저 처리하지 않을 때 호출됩니다. 제공되지 않으면 처리되지 않은 유도 요청이 자동으로 거부됩니다 |504| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP 유도 요청을 처리하기 위한 콜백입니다. MCP 서버가 사용자 입력을 요청하고 훅이 먼저 처리하지 않을 때 호출됩니다. 제공되지 않으면 처리되지 않은 유도 요청이 자동으로 거부됩니다 |

505| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. [구조화된 출력](/ko/agent-sdk/structured-outputs) 참조 |505| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 에이전트 결과의 출력 형식을 정의합니다. [구조화된 출력](/docs/ko/agent-sdk/structured-outputs) 참조 |

506| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/ko/settings) 객체 또는 설정 파일에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](/ko/agent-sdk/modifying-system-prompts#activate-an-output-style) 참조 |506| `outputStyle` | `string` | `undefined` | `Options` 필드가 아닙니다. 대신 인라인 [`settings`](/docs/ko/settings) 객체 또는 설정 파일에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](/docs/ko/agent-sdk/modifying-system-prompts#activate-an-output-style) 참조 |

507| `pathToClaudeCodeExecutable` | `string` | 번들된 네이티브 바이너리에서 자동 해결 | Claude Code 실행 파일의 경로입니다. 설치 중에 선택적 종속성을 건너뛰었거나 플랫폼이 지원되는 집합에 없을 때만 필요합니다 |507| `pathToClaudeCodeExecutable` | `string` | 번들된 네이티브 바이너리에서 자동 해결 | Claude Code 실행 파일의 경로입니다. 설치 중에 선택적 종속성을 건너뛰었거나 플랫폼이 지원되는 집합에 없을 때만 필요합니다 |

508| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | 세션의 권한 모드 |508| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | 세션의 권한 모드 |

509| `permissionPromptToolName` | `string` | `undefined` | 권한 프롬프트용 MCP 도구 이름 |509| `permissionPromptToolName` | `string` | `undefined` | 권한 프롬프트용 MCP 도구 이름 |

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

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

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

513| `promptSuggestions` | `boolean` | `false` | 프롬프트 제안을 활성화합니다. 각 턴 후 예측된 다음 사용자 프롬프트를 포함하는 `prompt_suggestion` 메시지를 내보냅니다 |513| `promptSuggestions` | `boolean` | `false` | 프롬프트 제안을 활성화합니다. 각 턴 후 예측된 다음 사용자 프롬프트를 포함하는 `prompt_suggestion` 메시지를 내보냅니다 |

514| `resume` | `string` | `undefined` | 재개할 세션 ID |514| `resume` | `string` | `undefined` | 재개할 세션 ID |

515| `resumeSessionAt` | `string` | `undefined` | 특정 메시지 UUID에서 세션 재개 |515| `resumeSessionAt` | `string` | `undefined` | 특정 메시지 UUID에서 세션 재개 |

516| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | 프로그래밍 방식으로 샌드박스 동작을 구성합니다. [샌드박스 설정](#sandboxsettings) 참조 |516| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | 프로그래밍 방식으로 샌드박스 동작을 구성합니다. [샌드박스 설정](#sandboxsettings) 참조 |

517| `sessionId` | `string` | 자동 생성 | 자동 생성하는 대신 세션에 특정 UUID를 사용합니다 |517| `sessionId` | `string` | 자동 생성 | 자동 생성하는 대신 세션에 특정 UUID를 사용합니다 |

518| `sessionStore` | [`SessionStore`](/ko/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 세션 대화를 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있습니다. [세션을 외부 저장소에 유지](/ko/agent-sdk/session-storage) 참조 |518| `sessionStore` | [`SessionStore`](/docs/ko/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 세션 대화를 외부 백엔드로 미러링하여 모든 호스트가 이를 재개할 수 있습니다. [세션을 외부 저장소에 유지](/docs/ko/agent-sdk/session-storage) 참조 |

519| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *알파.* `sessionStore`의 플러시 모드입니다. `sessionStore`가 설정되지 않으면 무시됩니다 |519| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *알파.* `sessionStore`의 플러시 모드입니다. `sessionStore`가 설정되지 않으면 무시됩니다 |

520| `settings` | `string \| Settings` | `undefined` | 인라인 [설정](/ko/settings) 객체 또는 설정 파일의 경로입니다. [우선순위 순서](/ko/settings#settings-precedence)에서 플래그 설정 계층을 채웁니다. [`applyFlagSettings()`](#applyflagsettings)로 런타임에 변경합니다 |520| `settings` | `string \| Settings` | `undefined` | 인라인 [설정](/docs/ko/settings) 객체 또는 설정 파일의 경로입니다. [우선순위 순서](/docs/ko/settings#settings-precedence)에서 플래그 설정 계층을 채웁니다. [`applyFlagSettings()`](#applyflagsettings)로 런타임에 변경합니다 |

521| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 기본값 (모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`을 전달합니다. 관리되는 정책 설정은 어쨌든 로드됩니다. 서버 관리 설정은 조직 자격 증명으로 세션이 [적격 구성](/ko/server-managed-settings#platform-availability)에서 인증할 때 가져옵니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하여 이 옵션과 관계없이 읽히는 입력과 이를 비활성화하는 방법을 확인하세요 |521| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 기본값 (모든 소스) | 로드할 파일 시스템 설정을 제어합니다. 사용자, 프로젝트 및 로컬 설정을 비활성화하려면 `[]`을 전달합니다. 관리되는 정책 설정은 어쨌든 로드됩니다. 서버 관리 설정은 조직 자격 증명으로 세션이 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 인증할 때 가져옵니다. [Claude Code 기능 사용](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하여 이 옵션과 관계없이 읽히는 입력과 이를 비활성화하는 방법을 확인하세요 |

522| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용 가능한 스킬입니다. 모든 발견된 스킬을 활성화하려면 `'all'`을 전달하거나 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowedTools`에 Skill 도구를 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `'Skill'`을 포함합니다. [스킬](/ko/agent-sdk/skills) 참조 |522| `skills` | `string[] \| 'all'` | `undefined` | 세션에서 사용 가능한 스킬입니다. 모든 발견된 스킬을 활성화하려면 `'all'`을 전달하거나 스킬 이름 목록을 전달합니다. 설정하면 SDK는 `allowedTools`에 Skill 도구를 자동으로 추가합니다. `tools`도 전달하는 경우 해당 목록에 `'Skill'`을 포함합니다. [스킬](/docs/ko/agent-sdk/skills) 참조 |

523| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code 프로세스를 생성하는 사용자 정의 함수입니다. VM, 컨테이너 또는 원격 환경에서 Claude Code를 실행하는 데 사용합니다 |523| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code 프로세스를 생성하는 사용자 정의 함수입니다. VM, 컨테이너 또는 원격 환경에서 Claude Code를 실행하는 데 사용합니다 |

524| `stderr` | `(data: string) => void` | `undefined` | stderr 출력에 대한 콜백 |524| `stderr` | `(data: string) => void` | `undefined` | stderr 출력에 대한 콜백 |

525| `strictMcpConfig` | `boolean` | `false` | `mcpServers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인 제공 MCP 서버 및 [claude.ai 커넥터](/ko/mcp#use-mcp-servers-from-claude-ai)를 무시합니다 |525| `strictMcpConfig` | `boolean` | `false` | `mcpServers`에 전달된 서버만 사용하고 프로젝트 `.mcp.json`, 사용자 설정, 플러그인 제공 MCP 서버 및 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai)를 무시합니다 |

526| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달합니다. 프리셋 객체 형식을 사용할 때 `append`를 추가하여 추가 지침으로 확장하고, `excludeDynamicSections: true`를 설정하여 세션별 컨텍스트를 첫 번째 사용자 메시지로 이동하여 [머신 간 프롬프트 캐시 재사용 개선](/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |526| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (최소 프롬프트) | 시스템 프롬프트 구성입니다. 사용자 정의 프롬프트의 경우 문자열을 전달하거나, Claude Code의 시스템 프롬프트를 사용하려면 `{ type: 'preset', preset: 'claude_code' }`를 전달합니다. 프리셋 객체 형식을 사용할 때 `append`를 추가하여 추가 지침으로 확장하고, `excludeDynamicSections: true`를 설정하여 세션별 컨텍스트를 첫 번째 사용자 메시지로 이동하여 [머신 간 프롬프트 캐시 재사용 개선](/docs/ko/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

527| `taskBudget` | `{ total: number }` | `undefined` | *알파.* API 측 작업 예산 (토큰 단위)입니다. 설정하면 모델은 도구 사용을 조절하고 제한 전에 마무리할 수 있도록 남은 토큰 예산을 알려집니다 |527| `taskBudget` | `{ total: number }` | `undefined` | *알파.* API 측 작업 예산 (토큰 단위)입니다. 설정하면 모델은 도구 사용을 조절하고 제한 전에 마무리할 수 있도록 남은 토큰 예산을 알려집니다 |

528| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. [`ThinkingConfig`](#thinkingconfig) 참조 |528| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 지원되는 모델의 경우 `{ type: 'adaptive' }` | Claude의 사고/추론 동작을 제어합니다. [`ThinkingConfig`](#thinkingconfig) 참조 |

529| `title` | `string` | `undefined` | 세션의 표시 제목입니다. `resume` 또는 `continue`를 통해 재개할 때 재개된 세션의 지속된 제목이 우선합니다. [`renameSession()`](#renamesession)을 사용하여 기존 세션의 제목을 변경합니다 |529| `title` | `string` | `undefined` | 세션의 표시 제목입니다. `resume` 또는 `continue`를 통해 재개할 때 재개된 세션의 지속된 제목이 우선합니다. [`renameSession()`](#renamesession)을 사용하여 기존 세션의 제목을 변경합니다 |

552```552```

553 553 

554* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 타임아웃 (밀리초 단위). 기본값 `600000`. 메인 루프 및 모든 서브에이전트에 적용됩니다.554* `API_TIMEOUT_MS`: Anthropic 클라이언트의 요청당 타임아웃 (밀리초 단위). 기본값 `600000`. 메인 루프 및 모든 서브에이전트에 적용됩니다.

555* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수. 기본값 `10`, 최대 `15`로 제한됩니다. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다. 더 긴 중단을 기다려야 하는 무인 실행의 경우 `CLAUDE_CODE_RETRY_WATCHDOG=1`을 설정하여 용량 오류를 무한정 재시도합니다. 그리고 {/* min-version: 2.1.199 */}Claude Code v2.1.199부터 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.555* `CLAUDE_CODE_MAX_RETRIES`: 최대 API 재시도 횟수. 기본값 `10`, 최대 `15`로 제한됩니다. 각 재시도는 자체 `API_TIMEOUT_MS` 윈도우를 가지므로 최악의 경우 벽시간은 대략 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 더하기 백오프입니다. 더 긴 중단을 기다려야 하는 무인 실행의 경우 `CLAUDE_CODE_RETRY_WATCHDOG=1`을 설정하여 용량 오류를 무한정 재시도합니다. 그리고 Claude Code v2.1.199부터 다른 일시적 오류의 기본값을 `300`으로 올리고 이 변수의 상한을 제거합니다.

556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트에 대한 정지 감시견입니다. 기본값 `600000`. 각 스트림 이벤트에서 재설정되며, 정지 시 서브에이전트를 중단하고 작업을 실패로 표시하며 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: `run_in_background`으로 시작된 서브에이전트에 대한 정지 감시견입니다. 기본값 `600000`. 각 스트림 이벤트에서 재설정되며, 정지 시 서브에이전트를 중단하고 작업을 실패로 표시하며 부분 결과와 함께 오류를 부모에게 표시합니다. 동기 서브에이전트에는 적용되지 않습니다.

557* `CLAUDE_ENABLE_STREAM_WATCHDOG` 및 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 고정됩니다. 중단된 요청은 일반 재시도 경로를 거칩니다.557* `CLAUDE_ENABLE_STREAM_WATCHDOG` 및 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: 헤더가 도착했지만 응답 본문이 스트리밍을 중지할 때 요청을 중단합니다. 감시견은 모든 공급자에 대해 기본적으로 켜져 있습니다. `CLAUDE_ENABLE_STREAM_WATCHDOG=0`으로 설정하여 비활성화합니다. `CLAUDE_STREAM_IDLE_TIMEOUT_MS`는 기본값 `300000`이고 해당 최소값으로 고정됩니다. 중단된 요청은 일반 재시도 경로를 거칩니다.

558 558 

594</h4>594</h4>

595 595 

596| 메서드 | 설명 |596| 메서드 | 설명 |

597| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |597| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

598| `interrupt()` | 쿼리를 중단합니다. 스트리밍 입력 모드에서만 사용 가능합니다. {/* min-version: 2.1.205 */}CLI가 [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 광고할 때 중단을 견디는 대기 중인 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)로 해결됩니다. v2.1.205 이전의 CLI에서는 `undefined`로 해결됩니다 |598| `interrupt()` | 쿼리를 중단합니다. 스트리밍 입력 모드에서만 사용 가능합니다. CLI가 [`SDKSystemMessage.capabilities`](#sdksystemmessage)에서 `interrupt_receipt_v1` 기능을 광고할 때 중단을 견디는 대기 중인 메시지를 나열하는 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)로 해결됩니다. v2.1.205 이전의 CLI에서는 `undefined`로 해결됩니다 |

599| `rewindFiles(userMessageId, options?)` | 파일을 지정된 사용자 메시지의 상태로 복원합니다. 변경 사항을 미리 보려면 `{ dryRun: true }`를 전달합니다. `enableFileCheckpointing: true`가 필요합니다. [파일 체크포인팅](/ko/agent-sdk/file-checkpointing) 참조 |599| `rewindFiles(userMessageId, options?)` | 파일을 지정된 사용자 메시지의 상태로 복원합니다. 변경 사항을 미리 보려면 `{ dryRun: true }`를 전달합니다. `enableFileCheckpointing: true`가 필요합니다. [파일 체크포인팅](/docs/ko/agent-sdk/file-checkpointing) 참조 |

600| `setPermissionMode()` | 권한 모드를 변경합니다 (스트리밍 입력 모드에서만 사용 가능) |600| `setPermissionMode()` | 권한 모드를 변경합니다 (스트리밍 입력 모드에서만 사용 가능) |

601| `setModel()` | 모델을 변경합니다 (스트리밍 입력 모드에서만 사용 가능) |601| `setModel()` | 모델을 변경합니다 (스트리밍 입력 모드에서만 사용 가능) |

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

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

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

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

606| `supportedCommands()` | 사용 가능한 슬래시 명령을 반환합니다 |606| `supportedCommands()` | 사용 가능한 슬래시 명령을 반환합니다 |

607| `supportedModels()` | 표시 정보를 포함한 사용 가능한 모델을 반환합니다 |607| `supportedModels()` | 표시 정보를 포함한 사용 가능한 모델을 반환합니다 |

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

619 `applyFlagSettings()`619 `applyFlagSettings()`

620</h4>620</h4>

621 621 

622실행 중인 세션에서 [설정](/ko/settings)을 변경하고 쿼리를 다시 시작하지 않습니다. 전용 설정자가 없는 설정이 변경되어야 할 때 사용합니다. 예를 들어 에이전트가 신뢰할 수 없는 입력을 읽은 후 `permissions`를 강화합니다. `setModel()` 및 `setPermissionMode()`는 이 두 키에 대한 전용 설정자입니다. `applyFlagSettings()`는 설정 키의 모든 부분 집합을 허용하는 일반 형식이며, 여기에 `model`을 전달하는 것은 `setModel()`과 동일하게 작동합니다.622실행 중인 세션에서 [설정](/docs/ko/settings)을 변경하고 쿼리를 다시 시작하지 않습니다. 전용 설정자가 없는 설정이 변경되어야 할 때 사용합니다. 예를 들어 에이전트가 신뢰할 수 없는 입력을 읽은 후 `permissions`를 강화합니다. `setModel()` 및 `setPermissionMode()`는 이 두 키에 대한 전용 설정자입니다. `applyFlagSettings()`는 설정 키의 모든 부분 집합을 허용하는 일반 형식이며, 여기에 `model`을 전달하는 것은 `setModel()`과 동일하게 작동합니다.

623 623 

624다음 턴에 적용되는 키만 있습니다:624다음 턴에 적용되는 키만 있습니다:

625 625 

626* **다음 턴에 적용됨**: `model`, `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. `agent`를 전환하면 해당 에이전트의 모델 재정의, 훅 및 시스템 프롬프트도 다음 턴에 적용됩니다.626* **다음 턴에 적용됨**: `model`, `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. `agent`를 전환하면 해당 에이전트의 모델 재정의, 훅 및 시스템 프롬프트도 다음 턴에 적용됩니다.

627* **세션 중 효과 없음**: 시스템 프롬프트 옵션입니다. 이들은 시작 시 한 번 해결되므로 실행 중인 세션은 호출이 성공하더라도 원본 값을 유지합니다. 이를 변경하려면 새 세션을 시작합니다.627* **세션 중 효과 없음**: 시스템 프롬프트 옵션입니다. 이들은 시작 시 한 번 해결되므로 실행 중인 세션은 호출이 성공하더라도 원본 값을 유지합니다. 이를 변경하려면 새 세션을 시작합니다.

628 628 

629`effortLevel`은 [노력 수준](/ko/model-config#adjust-effort-level) 이름을 허용합니다. 또한 `"ultracode"`를 허용하며, 이는 세션을 `xhigh` 노력으로 실행하고 [ultracode](/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. `Settings` 타입은 해당 값 없이 `effortLevel`을 선언하므로 TypeScript에서 동등한 `{ ultracode: true }`를 전달합니다. {/* min-version: 2.1.203 */}`ultracode` 값은 Claude Code v2.1.203 이상이 필요하며 설정 파일의 `effortLevel` 키가 아닌 `applyFlagSettings()`에서만 허용됩니다.629`effortLevel`은 [노력 수준](/docs/ko/model-config#adjust-effort-level) 이름을 허용합니다. 또한 `"ultracode"`를 허용하며, 이는 세션을 `xhigh` 노력으로 실행하고 [ultracode](/docs/ko/workflows#let-claude-decide-with-ultracode)를 켭니다. `Settings` 타입은 해당 값 없이 `effortLevel`을 선언하므로 TypeScript에서 동등한 `{ ultracode: true }`를 전달합니다. `ultracode` 값은 Claude Code v2.1.203 이상이 필요하며 설정 파일의 `effortLevel` 키가 아닌 `applyFlagSettings()`에서만 허용됩니다.

630 630 

631값은 플래그 설정 계층에 기록되며, 이는 `query()`의 인라인 `settings` 옵션이 시작 시 채우는 계층과 동일합니다. 플래그 설정은 [설정 우선순위 순서](/ko/settings#settings-precedence)의 상단 근처에 있습니다: 사용자, 프로젝트 및 로컬 설정을 재정의하며, 관리되는 정책 설정만 이를 재정의할 수 있습니다. 이는 [우선순위 섹션](#settings-precedence)이 프로그래밍 방식의 옵션이라고 부르는 것과 동일한 계층입니다.631값은 플래그 설정 계층에 기록되며, 이는 `query()`의 인라인 `settings` 옵션이 시작 시 채우는 계층과 동일합니다. 플래그 설정은 [설정 우선순위 순서](/docs/ko/settings#settings-precedence)의 상단 근처에 있습니다: 사용자, 프로젝트 및 로컬 설정을 재정의하며, 관리되는 정책 설정만 이를 재정의할 수 있습니다. 이는 [우선순위 섹션](#settings-precedence)이 프로그래밍 방식의 옵션이라고 부르는 것과 동일한 계층입니다.

632 632 

633연속 호출은 최상위 키를 얕게 병합합니다. `{ permissions: {...} }`를 포함한 두 번째 호출은 이전 호출의 전체 `permissions` 객체를 대체하며 깊게 병합하지 않습니다. 플래그 계층에서 키를 지우고 낮은 우선순위 소스로 돌아가려면 해당 키에 `null`을 전달합니다. `undefined`를 전달하면 JSON 직렬화가 이를 삭제하므로 효과가 없습니다.633연속 호출은 최상위 키를 얕게 병합합니다. `{ permissions: {...} }`를 포함한 두 번째 호출은 이전 호출의 전체 `permissions` 객체를 대체하며 깊게 병합하지 않습니다. 플래그 계층에서 키를 지우고 낮은 우선순위 소스로 돌아가려면 해당 키에 `null`을 전달합니다. `undefined`를 전달하면 JSON 직렬화가 이를 삭제하므로 효과가 없습니다.

634 634 

714 714 

715* UUID가 있는 메시지만 나타납니다. 빈 배열은 다른 것이 실행되지 않음을 의미하지 않습니다.715* UUID가 있는 메시지만 나타납니다. 빈 배열은 다른 것이 실행되지 않음을 의미하지 않습니다.

716* 메인 스레드 메시지만 나열됩니다. 서브에이전트로 주소 지정된 메시지는 범위를 벗어납니다.716* 메인 스레드 메시지만 나열됩니다. 서브에이전트로 주소 지정된 메시지는 범위를 벗어납니다.

717* 목록에는 클라이언트가 보낸 적이 없는 UUID (예: [예약된 작업](/ko/scheduled-tasks) 트리거)가 포함될 수 있습니다. 오류로 취급하는 대신 인식하지 못하는 UUID를 무시합니다.717* 목록에는 클라이언트가 보낸 적이 없는 UUID (예: [예약된 작업](/docs/ko/scheduled-tasks) 트리거)가 포함될 수 있습니다. 오류로 취급하는 대신 인식하지 못하는 UUID를 무시합니다.

718 718 

719수신은 중단이 처리되는 순간에 찍은 스냅샷이며, 깨끗한 중단에서 중단된 턴의 [`SDKResultMessage`](#sdkresultmessage) 전에 도착합니다. 해당 결과 후 대기열을 검사하는 대신 수신을 읽습니다: 루프는 다음 대기 중인 턴을 즉시 시작하므로 결과 후 검사하는 대기열이 이미 변경되었습니다.719수신은 중단이 처리되는 순간에 찍은 스냅샷이며, 깨끗한 중단에서 중단된 턴의 [`SDKResultMessage`](#sdkresultmessage) 전에 도착합니다. 해당 결과 후 대기열을 검사하는 대신 수신을 읽습니다: 루프는 다음 대기 중인 턴을 즉시 시작하므로 결과 후 검사하는 대기열이 이미 변경되었습니다.

720 720 

792 기본 동작792 기본 동작

793</h4>793</h4>

794 794 

795`settingSources`가 생략되거나 `undefined`일 때 `query()`는 Claude Code CLI와 동일한 파일 시스템 설정을 로드합니다: 사용자, 프로젝트 및 로컬입니다. 관리되는 정책 설정은 모든 경우에 로드됩니다. 서버 관리 설정은 조직 자격 증명으로 세션이 [적격 구성](/ko/server-managed-settings#platform-availability)에서 인증할 때 가져옵니다. [Claude Code 기능 사용](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하여 이 옵션과 관계없이 읽히는 입력과 이를 비활성화하는 방법을 확인하세요.795`settingSources`가 생략되거나 `undefined`일 때 `query()`는 Claude Code CLI와 동일한 파일 시스템 설정을 로드합니다: 사용자, 프로젝트 및 로컬입니다. 관리되는 정책 설정은 모든 경우에 로드됩니다. 서버 관리 설정은 조직 자격 증명으로 세션이 [적격 구성](/docs/ko/server-managed-settings#platform-availability)에서 인증할 때 가져옵니다. [Claude Code 기능 사용](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하여 이 옵션과 관계없이 읽히는 입력과 이를 비활성화하는 방법을 확인하세요.

796 796 

797<h4 id="why-use-settingsources">797<h4 id="why-use-settingsources">

798 settingSources를 사용하는 이유798 settingSources를 사용하는 이유

913 913 

914도구 사용을 제어하기 위한 사용자 정의 권한 함수 타입입니다.914도구 사용을 제어하기 위한 사용자 정의 권한 함수 타입입니다.

915 915 

916함수는 대화형 권한 프롬프트의 SDK 대체입니다: [권한 평가 흐름](/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 해결될 때만 호출됩니다. `allowedTools` 항목, 설정 허용 규칙 또는 `acceptEdits` 또는 `bypassPermissions`와 같은 권한 모드에 의해 이미 승인된 도구 호출은 이를 호출하지 않습니다. 모든 도구 호출을 제어하려면 [`PreToolUse` 훅](/ko/agent-sdk/hooks)을 사용합니다.916함수는 대화형 권한 프롬프트의 SDK 대체입니다: [권한 평가 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)이 프롬프트로 해결될 때만 호출됩니다. `allowedTools` 항목, 설정 허용 규칙 또는 `acceptEdits` 또는 `bypassPermissions`와 같은 권한 모드에 의해 이미 승인된 도구 호출은 이를 호출하지 않습니다. 모든 도구 호출을 제어하려면 [`PreToolUse` 훅](/docs/ko/agent-sdk/hooks)을 사용합니다.

917 917 

918`AskUserQuestion`, [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구 및 [조직이 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구는 허용 규칙이 일치하더라도 함수에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다.918`AskUserQuestion`, [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구 및 [조직이 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)한 커넥터 도구는 허용 규칙이 일치하더라도 함수에 도달합니다. `dontAsk` 모드에서는 대신 거부됩니다.

919 919 

920```typescript theme={null}920```typescript theme={null}

921type CanUseTool = (921type CanUseTool = (

985 985 

986| 필드 | 타입 | 설명 |986| 필드 | 타입 | 설명 |

987| :------------------------------ | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |987| :------------------------------ | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |

988| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | [`AskUserQuestion`](/ko/agent-sdk/user-input#question-format) 옵션의 `preview` 필드를 옵트인하고 콘텐츠 형식을 설정합니다. 설정하지 않으면 Claude는 미리보기를 내보내지 않습니다 |988| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | [`AskUserQuestion`](/docs/ko/agent-sdk/user-input#question-format) 옵션의 `preview` 필드를 옵트인하고 콘텐츠 형식을 설정합니다. 설정하지 않으면 Claude는 미리보기를 내보내지 않습니다 |

989 989 

990<h3 id="mcpserverconfig">990<h3 id="mcpserverconfig">

991 `McpServerConfig`991 `McpServerConfig`

1091];1091];

1092```1092```

1093 1093 

1094플러그인 생성 및 사용에 대한 완전한 정보는 [플러그인](/ko/agent-sdk/plugins)을 참조하세요.1094플러그인 생성 및 사용에 대한 완전한 정보는 [플러그인](/docs/ko/agent-sdk/plugins)을 참조하세요.

1095 1095 

1096<h2 id="message-types">1096<h2 id="message-types">

1097 메시지 타입1097 메시지 타입

1210};1210};

1211```1211```

1212 1212 

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

1214 1214 

1215<h3 id="sdkresultmessage">1215<h3 id="sdkresultmessage">

1216 `SDKResultMessage`1216 `SDKResultMessage`

1279 1279 

1280`origin` 필드는 이 결과를 트리거한 사용자 메시지의 [`SDKMessageOrigin`](#sdkmessageorigin)을 전달합니다. 백그라운드 작업이 완료되고 SDK가 합성 후속 턴을 주입할 때, 결과 `SDKResultMessage`는 `origin: { kind: "task-notification" }`을 전달합니다. 이 필드를 확인하여 프롬프트에 답하는 결과와 백그라운드 작업 후속을 위해 내보낸 결과를 구분하여 후자를 라우팅하거나 억제할 수 있습니다. 이 필드는 시작 오류와 같이 사용자 턴 이전에 내보낸 결과에는 없습니다.1280`origin` 필드는 이 결과를 트리거한 사용자 메시지의 [`SDKMessageOrigin`](#sdkmessageorigin)을 전달합니다. 백그라운드 작업이 완료되고 SDK가 합성 후속 턴을 주입할 때, 결과 `SDKResultMessage`는 `origin: { kind: "task-notification" }`을 전달합니다. 이 필드를 확인하여 프롬프트에 답하는 결과와 백그라운드 작업 후속을 위해 내보낸 결과를 구분하여 후자를 라우팅하거나 억제할 수 있습니다. 이 필드는 시작 오류와 같이 사용자 턴 이전에 내보낸 결과에는 없습니다.

1281 1281 

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

1283 1283 

1284<h3 id="sdksystemmessage">1284<h3 id="sdksystemmessage">

1285 `SDKSystemMessage`1285 `SDKSystemMessage`

1313};1313};

1314```1314```

1315 1315 

1316{/* min-version: 2.1.205 */}

1317 

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

1319 1317 

1320| 기능 | 의미 |1318| 기능 | 의미 |

1396 `SDKPluginInstallMessage`1394 `SDKPluginInstallMessage`

1397</h3>1395</h3>

1398 1396 

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

1400 1398 

1401```typescript theme={null}1399```typescript theme={null}

1402type SDKPluginInstallMessage = {1400type SDKPluginInstallMessage = {

1479```1477```

1480 1478 

1481| `kind` | 의미 |1479| `kind` | 의미 |

1482| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1480| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1483| `human` | 최종 사용자의 직접 입력입니다. 사용자 메시지에서 없는 `origin`도 인간 입력을 의미합니다. |1481| `human` | 최종 사용자의 직접 입력입니다. 사용자 메시지에서 없는 `origin`도 인간 입력을 의미합니다. |

1484| `channel` | [채널](/ko/channels)에 도착한 메시지입니다. `server`는 소스 MCP 서버 이름입니다. |1482| `channel` | [채널](/docs/ko/channels)에 도착한 메시지입니다. `server`는 소스 MCP 서버 이름입니다. |

1485| `peer` | 다른 에이전트의 메시지입니다. 프로세스 내 [팀원](/ko/agent-teams)이 `SendMessage`를 통해 `main`으로 보내는 경우, `from`은 팀원의 이름이고 `senderTaskId`는 해당 작업 ID입니다. 다른 로컬 Claude Code 프로세스와 같은 교차 세션 피어의 경우, `from`은 발신자 주소이고 `senderTaskId`는 없습니다. {/* min-version: 2.1.205 */}`name` 및 `body`는 Claude Code v2.1.205 이상이 필요합니다. `name`은 발신자의 표시 이름이며 Claude Code에서 정규화됩니다: 유니코드 제어, 형식, 서로게이트 및 줄 또는 단락 구분자 코드 포인트를 제거한 다음 결과를 자르고 64개 코드 포인트로 제한하고 줄임표를 추가합니다. `body`는 피어 봉투가 제거된 디코딩된 메시지 본문이며, 모델이 보는 것과 바이트 정확합니다. 팀원 메시지의 경우 `body`는 항상 존재합니다. 교차 세션 피어의 경우 Claude Code에서 형성한 정확히 하나의 피어 봉투인 경우에만 존재합니다. `name` 및 `body`를 렌더링하고 메시지 텍스트를 다시 파싱하지 마십시오. |1483| `peer` | 다른 에이전트의 메시지입니다. 프로세스 내 [팀원](/docs/ko/agent-teams)이 `SendMessage`를 통해 `main`으로 보내는 경우, `from`은 팀원의 이름이고 `senderTaskId`는 해당 작업 ID입니다. 다른 로컬 Claude Code 프로세스와 같은 교차 세션 피어의 경우, `from`은 발신자 주소이고 `senderTaskId`는 없습니다. `name` 및 `body`는 Claude Code v2.1.205 이상이 필요합니다. `name`은 발신자의 표시 이름이며 Claude Code에서 정규화됩니다: 유니코드 제어, 형식, 서로게이트 및 줄 또는 단락 구분자 코드 포인트를 제거한 다음 결과를 자르고 64개 코드 포인트로 제한하고 줄임표를 추가합니다. `body`는 피어 봉투가 제거된 디코딩된 메시지 본문이며, 모델이 보는 것과 바이트 정확합니다. 팀원 메시지의 경우 `body`는 항상 존재합니다. 교차 세션 피어의 경우 Claude Code에서 형성한 정확히 하나의 피어 봉투인 경우에만 존재합니다. `name` 및 `body`를 렌더링하고 메시지 텍스트를 다시 파싱하지 마십시오. |

1486| `task-notification` | 백그라운드 작업이 완료된 후 주입된 합성 턴입니다. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하십시오. |1484| `task-notification` | 백그라운드 작업이 완료된 후 주입된 합성 턴입니다. [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)를 참조하십시오. |

1487| `coordinator` | [에이전트 팀](/ko/agent-teams)의 팀 코디네이터로부터의 메시지입니다. |1485| `coordinator` | [에이전트 팀](/docs/ko/agent-teams)의 팀 코디네이터로부터의 메시지입니다. |

1488| `auto-continuation` | 새로운 사용자 입력 없이 세션이 계속될 때 주입된 합성 턴입니다. 예를 들어 후속 프롬프트를 트리거하는 명령 결과입니다. |1486| `auto-continuation` | 새로운 사용자 입력 없이 세션이 계속될 때 주입된 합성 턴입니다. 예를 들어 후속 프롬프트를 트리거하는 명령 결과입니다. |

1489 1487 

1490<h2 id="hook-types">1488<h2 id="hook-types">

1491 훅 타입1489 훅 타입

1492</h2>1490</h2>

1493 1491 

1494훅 사용에 대한 포괄적인 가이드, 예제 및 일반적인 패턴은 [훅 가이드](/ko/agent-sdk/hooks)를 참조하세요.1492훅 사용에 대한 포괄적인 가이드, 예제 및 일반적인 패턴은 [훅 가이드](/docs/ko/agent-sdk/hooks)를 참조하세요.

1495 1493 

1496<h3 id="hookevent">1494<h3 id="hookevent">

1497 `HookEvent`1495 `HookEvent`

1600};1598};

1601```1599```

1602 1600 

1603`prompt_id` 필드는 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/ko/monitoring-usage#event-correlation-attributes)과 일치하며 첫 번째 사용자 입력까지는 없습니다. Claude Code v2.1.196 이상이 필요합니다.1601`prompt_id` 필드는 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/docs/ko/monitoring-usage#event-correlation-attributes)과 일치하며 첫 번째 사용자 입력까지는 없습니다. Claude Code v2.1.196 이상이 필요합니다.

1604 1602 

1605<h4 id="pretoolusehookinput">1603<h4 id="pretoolusehookinput">

1606 `PreToolUseHookInput`1604 `PreToolUseHookInput`

2071};2069};

2072```2070```

2073 2071 

2074실행 중에 사용자에게 명확히 하는 질문을 합니다. 사용 세부 정보는 [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input#handle-clarifying-questions)를 참조하세요.2072실행 중에 사용자에게 명확히 하는 질문을 합니다. 사용 세부 정보는 [승인 및 사용자 입력 처리](/docs/ko/agent-sdk/user-input#handle-clarifying-questions)를 참조하세요.

2075 2073 

2076<h3 id="bash">2074<h3 id="bash">

2077 Bash2075 Bash

2110};2108};

2111```2109```

2112 2110 

2113백그라운드 소스를 실행하고 각 이벤트를 Claude에 전달하므로 폴링 없이 반응할 수 있습니다: `command`는 스크립트를 실행하고 stdout 라인당 하나의 이벤트를 내보내며, `ws`는 WebSocket을 열고 텍스트 프레임당 하나의 이벤트를 내보냅니다. `command` 또는 `ws` 중 정확히 하나를 제공합니다. {/* min-version: 2.1.195 */}`ws` 소스는 Claude Code v2.1.195 이상이 필요합니다.2111백그라운드 소스를 실행하고 각 이벤트를 Claude에 전달하므로 폴링 없이 반응할 수 있습니다: `command`는 스크립트를 실행하고 stdout 라인당 하나의 이벤트를 내보내며, `ws`는 WebSocket을 열고 텍스트 프레임당 하나의 이벤트를 내보냅니다. `command` 또는 `ws` 중 정확히 하나를 제공합니다. `ws` 소스는 Claude Code v2.1.195 이상이 필요합니다.

2114 2112 

2115로그 테일과 같은 세션 길이 감시의 경우 `persistent: true`를 설정합니다. Monitor가 명령을 실행할 때, Bash와 동일한 권한 규칙을 따릅니다. WebSocket 감시는 별도로 승인을 요청합니다. 동작 및 공급자 가용성은 [Monitor 도구 참조](/ko/tools-reference#monitor-tool)를 참조하세요.2113로그 테일과 같은 세션 길이 감시의 경우 `persistent: true`를 설정합니다. Monitor가 명령을 실행할 때, Bash와 동일한 권한 규칙을 따릅니다. WebSocket 감시는 별도로 승인을 요청합니다. 동작 및 공급자 가용성은 [Monitor 도구 참조](/docs/ko/tools-reference#monitor-tool)를 참조하세요.

2116 2114 

2117<h3 id="taskoutput">2115<h3 id="taskoutput">

2118 TaskOutput2116 TaskOutput

2234};2232};

2235```2233```

2236 2234 

2237ID로 실행 중인 백그라운드 작업 또는 셸을 중지합니다. {/* min-version: 2.1.198 */}v2.1.198부터 `task_id`는 에이전트 팀 팀원 또는 에이전트 ID 또는 이름으로 명명된 백그라운드 에이전트도 수락합니다.2235ID로 실행 중인 백그라운드 작업 또는 셸을 중지합니다. v2.1.198부터 `task_id`는 에이전트 팀 팀원 또는 에이전트 ID 또는 이름으로 명명된 백그라운드 에이전트도 수락합니다.

2238 2236 

2239<h3 id="notebookedit">2237<h3 id="notebookedit">

2240 NotebookEdit2238 NotebookEdit

2301};2299};

2302```2300```

2303 2301 

2304[동적 워크플로우](/ko/workflows)를 실행합니다: 백그라운드에서 많은 서브에이전트를 조율하고 하나의 통합된 결과를 반환하는 스크립트입니다. `Workflow` 도구는 Agent SDK v0.3.149 이상에서 사용 가능합니다. `script`, `name` 또는 `scriptPath` 중 최소 하나가 필요합니다.2302[동적 워크플로우](/docs/ko/workflows)를 실행합니다: 백그라운드에서 많은 서브에이전트를 조율하고 하나의 통합된 결과를 반환하는 스크립트입니다. `Workflow` 도구는 Agent SDK v0.3.149 이상에서 사용 가능합니다. `script`, `name` 또는 `scriptPath` 중 최소 하나가 필요합니다.

2305 2303 

2306| 필드 | 타입 | 설명 |2304| 필드 | 타입 | 설명 |

2307| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2305| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2330진행 상황을 추적하기 위한 구조화된 작업 목록을 만들고 관리합니다.2328진행 상황을 추적하기 위한 구조화된 작업 목록을 만들고 관리합니다.

2331 2329 

2332<Note>2330<Note>

2333 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate` 및 `TaskList`를 사용하세요. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.2331 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate` 및 `TaskList`를 사용하세요. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/docs/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.

2334</Note>2332</Note>

2335 2333 

2336<h3 id="taskcreate">2334<h3 id="taskcreate">

2570 2568 

2571서브에이전트의 결과를 반환합니다. `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 원격 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`이며, 여기서 `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다.2569서브에이전트의 결과를 반환합니다. `status` 필드에서 구분됩니다: 완료된 작업의 경우 `"completed"`, 백그라운드 작업의 경우 `"async_launched"`, Claude Code가 원격 클라우드 세션으로 전달한 작업의 경우 `"remote_launched"`이며, 여기서 `sessionUrl`은 해당 세션으로 연결되고 `taskId`는 이를 식별합니다.

2572 2570 

2573`resolvedModel` 필드는 `completed` 및 `async_launched` 변형에서 서브에이전트가 실제로 실행된 모델의 이름을 지정하며, 이는 [`availableModels`](/ko/model-config#restrict-model-selection) 또는 다른 재정의가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. {/* min-version: 2.1.174 */}이 필드는 Claude Code v2.1.174 이상이 필요합니다.2571`resolvedModel` 필드는 `completed` 및 `async_launched` 변형에서 서브에이전트가 실제로 실행된 모델의 이름을 지정하며, 이는 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 또는 다른 재정의가 적용될 때 요청된 `model` 입력과 다를 수 있습니다. 이 필드는 Claude Code v2.1.174 이상이 필요합니다.

2574 2572 

2575`completed` 변형에서 `worktreePath`는 서브에이전트가 격리된 git worktree에서 실행되었을 때 설정되며, `worktreeBranch`는 Claude Code가 생성했을 때 해당 worktree의 분기 이름을 지정합니다. `usage.service_tier`는 서브에이전트의 요청에 대해 API가 보고한 서비스 계층 문자열을 전달합니다.2573`completed` 변형에서 `worktreePath`는 서브에이전트가 격리된 git worktree에서 실행되었을 때 설정되며, `worktreeBranch`는 Claude Code가 생성했을 때 해당 worktree의 분기 이름을 지정합니다. `usage.service_tier`는 서브에이전트의 요청에 대해 API가 보고한 서비스 계층 문자열을 전달합니다.

2576 2574 

2936이전 및 업데이트된 작업 목록을 반환합니다.2934이전 및 업데이트된 작업 목록을 반환합니다.

2937 2935 

2938<Note>2936<Note>

2939 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.2937 TypeScript Agent SDK 0.3.142부터 `TodoWrite`는 기본적으로 비활성화됩니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. 모니터링 코드를 업데이트하려면 [작업 도구로 마이그레이션](/docs/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하거나, `CLAUDE_CODE_ENABLE_TASKS=0`을 설정하여 `TodoWrite`로 되돌립니다.

2940</Note>2938</Note>

2941 2939 

2942<h3 id="taskcreate-2">2940<h3 id="taskcreate-2">

3230```3228```

3231 3229 

3232| 필드 | 타입 | 설명 |3230| 필드 | 타입 | 설명 |

3233| :------------------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3231| :------------------------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3234| `value` | `string` | API 호출에서 전달할 모델 식별자 |3232| `value` | `string` | API 호출에서 전달할 모델 식별자 |

3235| `resolvedModel` | `string \| undefined` | 이 항목의 `value`가 확인되는 정규 와이어 모델 ID입니다. `sonnet`과 같은 별칭 항목은 `claude-sonnet-5`와 같은 명시적 모델 ID로 확인되므로, 호스트는 저장된 명시적 모델 ID를 이 별칭 항목이 포함하는 것과 일치시킬 수 있습니다. {/* min-version: 2.1.197 */}Claude Code v2.1.197 이상이 필요합니다. |3233| `resolvedModel` | `string \| undefined` | 이 항목의 `value`가 확인되는 정규 와이어 모델 ID입니다. `sonnet`과 같은 별칭 항목은 `claude-sonnet-5`와 같은 명시적 모델 ID로 확인되므로, 호스트는 저장된 명시적 모델 ID를 이 별칭 항목이 포함하는 것과 일치시킬 수 있습니다. Claude Code v2.1.197 이상이 필요합니다. |

3236| `displayName` | `string` | 사람이 읽을 수 있는 표시 이름 |3234| `displayName` | `string` | 사람이 읽을 수 있는 표시 이름 |

3237| `description` | `string` | 모델의 기능에 대한 설명 |3235| `description` | `string` | 모델의 기능에 대한 설명 |

3238| `supportsEffort` | `boolean \| undefined` | 이 모델이 노력 수준을 지원하는지 여부 |3236| `supportsEffort` | `boolean \| undefined` | 이 모델이 노력 수준을 지원하는지 여부 |

3327 `ModelUsage`3325 `ModelUsage`

3328</h3>3326</h3>

3329 3327 

3330결과 메시지에서 반환된 모델별 사용 통계입니다. `costUSD` 값은 클라이언트 측 추정입니다. [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking)에서 청구 주의 사항을 참조하세요.3328결과 메시지에서 반환된 모델별 사용 통계입니다. `costUSD` 값은 클라이언트 측 추정입니다. [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)에서 청구 주의 사항을 참조하세요.

3331 3329 

3332```typescript theme={null}3330```typescript theme={null}

3333type ModelUsage = {3331type ModelUsage = {

3392 `CallToolResult`3390 `CallToolResult`

3393</h3>3391</h3>

3394 3392 

3395MCP 도구 결과 타입 (`@modelcontextprotocol/sdk/types.js`에서). `structuredContent`는 `content`와 함께 반환될 수 있는 JSON 객체이며, 이미지 블록을 포함합니다. [구조화된 데이터 반환](/ko/agent-sdk/custom-tools#return-structured-data)을 참조하세요.3393MCP 도구 결과 타입 (`@modelcontextprotocol/sdk/types.js`에서). `structuredContent`는 `content`와 함께 반환될 수 있는 JSON 객체이며, 이미지 블록을 포함합니다. [구조화된 데이터 반환](/docs/ko/agent-sdk/custom-tools#return-structured-data)을 참조하세요.

3396 3394 

3397```typescript theme={null}3395```typescript theme={null}

3398type CallToolResult = {3396type CallToolResult = {

3742 3740 

3743시작 시 아무것도 내보내지지 않습니다. 세션의 CLI 프로세스가 시작되거나 다시 시작될 때마다 빈 집합으로 재설정하고 다음 멤버십 변경이 다시 채우도록 하세요.3741시작 시 아무것도 내보내지지 않습니다. 세션의 CLI 프로세스가 시작되거나 다시 시작될 때마다 빈 집합으로 재설정하고 다음 멤버십 변경이 다시 채우도록 하세요.

3744 3742 

3745{/* min-version: 2.1.203 */}Claude Code v2.1.203 이상이 필요합니다.3743Claude Code v2.1.203 이상이 필요합니다.

3746 3744 

3747```typescript theme={null}3745```typescript theme={null}

3748type SDKBackgroundTasksChangedMessage = {3746type SDKBackgroundTasksChangedMessage = {

3762 `SDKThinkingTokensMessage`3760 `SDKThinkingTokensMessage`

3763</h3>3761</h3>

3764 3762 

3765Claude가 사고 블록을 생성하는 동안 내보내집니다. 여기에는 지금까지 생성된 사고 토큰의 실행 추정치가 포함됩니다. `estimated_tokens`는 현재 사고 블록의 실행 합계이고 `estimated_tokens_delta`는 이 프레임에서 전달된 증분입니다. 진행 상황 표시에 사용하세요. 최상위 에이전트 루프의 최종 개수는 결과 메시지의 `usage.output_tokens`입니다. 이는 [서브에이전트 토큰을 포함하지 않습니다](/ko/agent-sdk/cost-tracking#get-the-total-cost-of-a-query). 전체 트리 회계를 위해 [`modelUsage`](#modelusage)를 사용하세요.3763Claude가 사고 블록을 생성하는 동안 내보내집니다. 여기에는 지금까지 생성된 사고 토큰의 실행 추정치가 포함됩니다. `estimated_tokens`는 현재 사고 블록의 실행 합계이고 `estimated_tokens_delta`는 이 프레임에서 전달된 증분입니다. 진행 상황 표시에 사용하세요. 최상위 에이전트 루프의 최종 개수는 결과 메시지의 `usage.output_tokens`입니다. 이는 [서브에이전트 토큰을 포함하지 않습니다](/docs/ko/agent-sdk/cost-tracking#get-the-total-cost-of-a-query). 전체 트리 회계를 위해 [`modelUsage`](#modelusage)를 사용하세요.

3766 3764 

3767{/* min-version: 2.1.153 */}Claude Code v2.1.153 이상이 필요합니다.3765Claude Code v2.1.153 이상이 필요합니다.

3768 3766 

3769```typescript theme={null}3767```typescript theme={null}

3770type SDKThinkingTokensMessage = {3768type SDKThinkingTokensMessage = {

3817};3815};

3818```3816```

3819 3817 

3820{/* min-version: 2.1.181 */}`errorCode`가 `"credits_required"`일 때, 거부는 포함된 사용량이 소진된 claude.ai 구독에서 발생하며, 사용자가 사용 크레딧을 구매할 때까지 세션을 계속할 수 없습니다. `canUserPurchaseCredits`는 인증된 사용자가 계정에 대한 크레딧을 구매할 수 있는지 여부를 나타내고, `hasChargeableSavedPaymentMethod`는 저장된 결제 방법이 파일에 있는지 여부를 나타냅니다. 세 필드 모두 크레딧 필수 거부가 아닌 속도 제한 이벤트에서는 없습니다. Claude Code v2.1.181 이상이 필요합니다.3818`errorCode`가 `"credits_required"`일 때, 거부는 포함된 사용량이 소진된 claude.ai 구독에서 발생하며, 사용자가 사용 크레딧을 구매할 때까지 세션을 계속할 수 없습니다. `canUserPurchaseCredits`는 인증된 사용자가 계정에 대한 크레딧을 구매할 수 있는지 여부를 나타내고, `hasChargeableSavedPaymentMethod`는 저장된 결제 방법이 파일에 있는지 여부를 나타냅니다. 세 필드 모두 크레딧 필수 거부가 아닌 속도 제한 이벤트에서는 없습니다. Claude Code v2.1.181 이상이 필요합니다.

3821 3819 

3822<h3 id="sdklocalcommandoutputmessage">3820<h3 id="sdklocalcommandoutputmessage">

3823 `SDKLocalCommandOutputMessage`3821 `SDKLocalCommandOutputMessage`

3881};3879};

3882```3880```

3883 3881 

3884{/* min-version: 2.1.203 */}SDK의 게시된 타이핑은 Claude Code v2.1.203 이상에서 `SDKConversationResetMessage`를 선언합니다. v2.1.203 이전에는 `SDKMessage`가 타입을 선언하지 않고 참조했으므로, `skipLibCheck`가 비활성화되었을 때 `type === "conversation_reset"`에 대한 좁혀지기가 타입 검사에 실패했습니다.3882SDK의 게시된 타이핑은 Claude Code v2.1.203 이상에서 `SDKConversationResetMessage`를 선언합니다. v2.1.203 이전에는 `SDKMessage`가 타입을 선언하지 않고 참조했으므로, `skipLibCheck`가 비활성화되었을 때 `type === "conversation_reset"`에 대한 좁혀지기가 타입 검사에 실패했습니다.

3885 3883 

3886<h3 id="aborterror">3884<h3 id="aborterror">

3887 `AbortError`3885 `AbortError`

3932| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 샌드박스 환경을 위한 사용자 정의 ripgrep 바이너리 구성 |3930| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 샌드박스 환경을 위한 사용자 정의 ripgrep 바이너리 구성 |

3933 3931 

3934<Note>3932<Note>

3935 샌드박스는 플랫폼 지원에 따라 다르며, Linux에서는 `bubblewrap` 및 `socat`과 같은 도구가 필요합니다. `enabled`가 `true`이고 샌드박스를 시작할 수 없는 경우 `query()`는 `subtype: "error_during_execution"`이 있는 `result` 메시지를 보고하고 `errors`에 이유를 표시합니다. 단일 메시지 `query()` 호출의 경우 SDK는 해당 오류 결과를 생성한 후 예외를 발생시키므로 루프를 try 블록으로 래핑하여 이를 지나 계속 진행합니다. 오류 계약에 대해서는 [결과 처리](/ko/agent-sdk/agent-loop#handle-the-result)를 참조합니다.3933 샌드박스는 플랫폼 지원에 따라 다르며, Linux에서는 `bubblewrap` 및 `socat`과 같은 도구가 필요합니다. `enabled`가 `true`이고 샌드박스를 시작할 수 없는 경우 `query()`는 `subtype: "error_during_execution"`이 있는 `result` 메시지를 보고하고 `errors`에 이유를 표시합니다. 단일 메시지 `query()` 호출의 경우 SDK는 해당 오류 결과를 생성한 후 예외를 발생시키므로 루프를 try 블록으로 래핑하여 이를 지나 계속 진행합니다. 오류 계약에 대해서는 [결과 처리](/docs/ko/agent-sdk/agent-loop#handle-the-result)를 참조합니다.

3936 3934 

3937 대신 샌드박스되지 않은 상태로 실행하려면 `failIfUnavailable: false`를 설정합니다.3935 대신 샌드박스되지 않은 상태로 실행하려면 `failIfUnavailable: false`를 설정합니다.

3938</Note>3936</Note>

3974 `SandboxNetworkConfig`3972 `SandboxNetworkConfig`

3975</h3>3973</h3>

3976 3974 

3977샌드박스 모드를 위한 네트워크 특정 구성입니다. 이러한 설정은 부모 [`SandboxSettings`](#sandboxsettings)에서 `enabled`가 `true`일 때 샌드박스된 Bash 명령에 적용됩니다. 이들은 [권한 규칙](/ko/permissions#webfetch)을 대신 사용하는 WebFetch 도구를 제한하지 않습니다.3975샌드박스 모드를 위한 네트워크 특정 구성입니다. 이러한 설정은 부모 [`SandboxSettings`](#sandboxsettings)에서 `enabled`가 `true`일 때 샌드박스된 Bash 명령에 적용됩니다. 이들은 [권한 규칙](/docs/ko/permissions#webfetch)을 대신 사용하는 WebFetch 도구를 제한하지 않습니다.

3978 3976 

3979```typescript theme={null}3977```typescript theme={null}

3980type SandboxNetworkConfig = {3978type SandboxNetworkConfig = {

3993| :------------------------ | :--------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |3991| :------------------------ | :--------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3994| `allowedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 있는 도메인 이름 |3992| `allowedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 있는 도메인 이름 |

3995| `deniedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 없는 도메인 이름입니다. `allowedDomains`보다 우선합니다 |3993| `deniedDomains` | `string[]` | `[]` | 샌드박스된 프로세스가 액세스할 수 없는 도메인 이름입니다. `allowedDomains`보다 우선합니다 |

3996| `allowManagedDomainsOnly` | `boolean` | `false` | 관리형 설정 전용입니다. [관리형 설정](/ko/permissions#managed-settings)에서 설정되었을 때 관리형 설정의 `allowedDomains` 항목만 적용되며 사용자, 프로젝트 또는 로컬 설정의 항목은 무시됩니다. SDK 옵션을 통해 설정되었을 때는 효과가 없습니다 |3994| `allowManagedDomainsOnly` | `boolean` | `false` | 관리형 설정 전용입니다. [관리형 설정](/docs/ko/permissions#managed-settings)에서 설정되었을 때 관리형 설정의 `allowedDomains` 항목만 적용되며 사용자, 프로젝트 또는 로컬 설정의 항목은 무시됩니다. SDK 옵션을 통해 설정되었을 때는 효과가 없습니다 |

3997| `allowLocalBinding` | `boolean` | `false` | 프로세스가 로컬 포트에 바인딩하도록 허용합니다 (예: 개발 서버의 경우) |3995| `allowLocalBinding` | `boolean` | `false` | 프로세스가 로컬 포트에 바인딩하도록 허용합니다 (예: 개발 서버의 경우) |

3998| `allowUnixSockets` | `string[]` | `[]` | 프로세스가 액세스할 수 있는 Unix 소켓 경로 (예: Docker 소켓) |3996| `allowUnixSockets` | `string[]` | `[]` | 프로세스가 액세스할 수 있는 Unix 소켓 경로 (예: Docker 소켓) |

3999| `allowAllUnixSockets` | `boolean` | `false` | 모든 Unix 소켓에 대한 액세스 허용 |3997| `allowAllUnixSockets` | `boolean` | `false` | 모든 Unix 소켓에 대한 액세스 허용 |

4001| `socksProxyPort` | `number` | `undefined` | 네트워크 요청을 위한 SOCKS 프록시 포트 |3999| `socksProxyPort` | `number` | `undefined` | 네트워크 요청을 위한 SOCKS 프록시 포트 |

4002 4000 

4003<Note>4001<Note>

4004 기본 제공 샌드박스 프록시는 요청된 호스트명을 기반으로 `allowedDomains`를 적용하며 TLS 트래픽을 종료하거나 검사하지 않으므로 [도메인 프론팅](https://en.wikipedia.org/wiki/Domain_fronting)과 같은 기술이 이를 우회할 수 있습니다. 자세한 내용은 [샌드박싱 보안 제한 사항](/ko/sandboxing#security-limitations)을 참조하고 TLS 종료 프록시 구성에 대해서는 [안전한 배포](/ko/agent-sdk/secure-deployment#traffic-forwarding)를 참조합니다.4002 기본 제공 샌드박스 프록시는 요청된 호스트명을 기반으로 `allowedDomains`를 적용하며 TLS 트래픽을 종료하거나 검사하지 않으므로 [도메인 프론팅](https://en.wikipedia.org/wiki/Domain_fronting)과 같은 기술이 이를 우회할 수 있습니다. 자세한 내용은 [샌드박싱 보안 제한 사항](/docs/ko/sandboxing#security-limitations)을 참조하고 TLS 종료 프록시 구성에 대해서는 [안전한 배포](/docs/ko/agent-sdk/secure-deployment#traffic-forwarding)를 참조합니다.

4005</Note>4003</Note>

4006 4004 

4007<h3 id="sandboxfilesystemconfig">4005<h3 id="sandboxfilesystemconfig">

4079<Warning>4077<Warning>

4080 `dangerouslyDisableSandbox: true`로 실행되는 명령은 전체 시스템 액세스 권한이 있습니다. `canUseTool` 핸들러가 이러한 요청을 신중하게 검증하는지 확인합니다.4078 `dangerouslyDisableSandbox: true`로 실행되는 명령은 전체 시스템 액세스 권한이 있습니다. `canUseTool` 핸들러가 이러한 요청을 신중하게 검증하는지 확인합니다.

4081 4079 

4082 `permissionMode`가 `bypassPermissions`로 설정되고 `allowUnsandboxedCommands`가 활성화되면 모델은 승인 프롬프트 없이 샌드박스 외부에서 명령을 자율적으로 실행할 수 있습니다 (명시적 [`ask` 규칙](/ko/agent-sdk/permissions#how-permissions-are-evaluated)은 여전히 하나를 강제합니다). 이 조합은 모델이 샌드박스 격리를 조용히 탈출하도록 효과적으로 허용합니다.4080 `permissionMode`가 `bypassPermissions`로 설정되고 `allowUnsandboxedCommands`가 활성화되면 모델은 승인 프롬프트 없이 샌드박스 외부에서 명령을 자율적으로 실행할 수 있습니다 (명시적 [`ask` 규칙](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)은 여전히 하나를 강제합니다). 이 조합은 모델이 샌드박스 격리를 조용히 탈출하도록 효과적으로 허용합니다.

4083</Warning>4081</Warning>

4084 4082 

4085<h2 id="see-also">4083<h2 id="see-also">

4086 참고 항목4084 참고 항목

4087</h2>4085</h2>

4088 4086 

4089* [SDK 개요](/ko/agent-sdk/overview) - 일반 SDK 개념4087* [SDK 개요](/docs/ko/agent-sdk/overview) - 일반 SDK 개념

4090* [Python SDK 참조](/ko/agent-sdk/python) - Python SDK 문서4088* [Python SDK 참조](/docs/ko/agent-sdk/python) - Python SDK 문서

4091* [CLI 참조](/ko/cli-reference) - 명령줄 인터페이스4089* [CLI 참조](/docs/ko/cli-reference) - 명령줄 인터페이스

4092* [일반적인 워크플로우](/ko/common-workflows) - 단계별 가이드4090* [일반적인 워크플로우](/docs/ko/common-workflows) - 단계별 가이드

12 12 

13명확화 질문의 경우 Claude가 질문과 옵션을 생성합니다. 사용자의 역할은 이를 사용자에게 제시하고 선택 사항을 반환하는 것입니다. 이 흐름에 자신의 질문을 추가할 수 없습니다. 사용자에게 직접 물어봐야 할 사항이 있으면 애플리케이션 로직에서 별도로 수행하십시오.13명확화 질문의 경우 Claude가 질문과 옵션을 생성합니다. 사용자의 역할은 이를 사용자에게 제시하고 선택 사항을 반환하는 것입니다. 이 흐름에 자신의 질문을 추가할 수 없습니다. 사용자에게 직접 물어봐야 할 사항이 있으면 애플리케이션 로직에서 별도로 수행하십시오.

14 14 

15콜백은 무기한 대기 상태로 유지될 수 있습니다. 콜백이 반환될 때까지 실행이 일시 중지되며, SDK는 쿼리 자체가 취소될 때만 대기를 취소합니다. 사용자가 프로세스가 합리적으로 실행 상태를 유지할 수 있는 것보다 더 오래 응답하는 데 시간이 걸릴 수 있다면, [`defer` 훅 결정](/ko/hooks#defer-a-tool-call-for-later)을 반환하십시오. 이를 통해 프로세스를 종료하고 나중에 지속된 세션에서 재개할 수 있습니다.15콜백은 무기한 대기 상태로 유지될 수 있습니다. 콜백이 반환될 때까지 실행이 일시 중지되며, SDK는 쿼리 자체가 취소될 때만 대기를 취소합니다. 사용자가 프로세스가 합리적으로 실행 상태를 유지할 수 있는 것보다 더 오래 응답하는 데 시간이 걸릴 수 있다면, [`defer` 훅 결정](/docs/ko/hooks#defer-a-tool-call-for-later)을 반환하십시오. 이를 통해 프로세스를 종료하고 나중에 지속된 세션에서 재개할 수 있습니다.

16 16 

17이 가이드는 각 유형의 요청을 감지하고 적절하게 응답하는 방법을 보여줍니다.17이 가이드는 각 유형의 요청을 감지하고 적절하게 응답하는 방법을 보여줍니다.

18 18 

44 44 

45콜백은 두 가지 경우에 실행됩니다.45콜백은 두 가지 경우에 실행됩니다.

46 46 

471. **도구가 승인 필요**: Claude가 [권한 규칙](/ko/agent-sdk/permissions) 또는 권한 모드에 의해 자동 승인되지 않은 도구를 사용하려고 합니다. 도구에 대해 `tool_name`을 확인합니다(예: `"Bash"`, `"Write"`).471. **도구가 승인 필요**: Claude가 [권한 규칙](/docs/ko/agent-sdk/permissions) 또는 권한 모드에 의해 자동 승인되지 않은 도구를 사용하려고 합니다. 도구에 대해 `tool_name`을 확인합니다(예: `"Bash"`, `"Write"`).

482. **Claude가 질문함**: Claude가 `AskUserQuestion` 도구를 호출합니다. `tool_name == "AskUserQuestion"`을 확인하여 다르게 처리합니다. `tools` 배열을 지정하는 경우 이것이 작동하려면 `AskUserQuestion`을 포함하십시오. 자세한 내용은 [명확화 질문 처리](#handle-clarifying-questions)를 참조하십시오.482. **Claude가 질문함**: Claude가 `AskUserQuestion` 도구를 호출합니다. `tool_name == "AskUserQuestion"`을 확인하여 다르게 처리합니다. `tools` 배열을 지정하는 경우 이것이 작동하려면 `AskUserQuestion`을 포함하십시오. 자세한 내용은 [명확화 질문 처리](#handle-clarifying-questions)를 참조하십시오.

49 49 

50<Warning>50<Warning>

51 **콜백은 자동 승인된 도구에 대해서는 실행되지 않습니다.** [권한 평가 흐름](/ko/agent-sdk/permissions#how-permissions-are-evaluated)의 이전 단계에서 허용 규칙이나 `acceptEdits` 또는 `bypassPermissions`와 같은 모드가 `canUseTool`을 확인하기 전에 호출을 해결합니다. `allowed_tools`에 도구를 나열하면, 요청이 질문 규칙이나 `plan` 모드에 의해 프롬프트로 다시 라우팅되지 않는 한 해당 도구에 대한 `canUseTool` 확인이 실행되지 않습니다. 모든 도구 호출에 적용되어야 하는 로직의 경우 흐름의 나머지 부분 전에 실행되고 요청을 허용, 거부 또는 수정할 수 있는 [`PreToolUse` 훅](/ko/agent-sdk/hooks)을 사용하십시오.51 **콜백은 자동 승인된 도구에 대해서는 실행되지 않습니다.** [권한 평가 흐름](/docs/ko/agent-sdk/permissions#how-permissions-are-evaluated)의 이전 단계에서 허용 규칙이나 `acceptEdits` 또는 `bypassPermissions`와 같은 모드가 `canUseTool`을 확인하기 전에 호출을 해결합니다. `allowed_tools`에 도구를 나열하면, 요청이 질문 규칙이나 `plan` 모드에 의해 프롬프트로 다시 라우팅되지 않는 한 해당 도구에 대한 `canUseTool` 확인이 실행되지 않습니다. 모든 도구 호출에 적용되어야 하는 로직의 경우 흐름의 나머지 부분 전에 실행되고 요청을 허용, 거부 또는 수정할 수 있는 [`PreToolUse` 훅](/docs/ko/agent-sdk/hooks)을 사용하십시오.

52 52 

53 `AskUserQuestion`, MCP 도구가 [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시되고, 커넥터 도구가 [조직에서 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools)된 경우 허용 규칙이 일치하더라도 콜백에 도달합니다. `dontAsk` 모드에서는 콜백을 호출하지 않고 이러한 호출이 거부됩니다.53 `AskUserQuestion`, MCP 도구가 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시되고, 커넥터 도구가 [조직에서 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools)된 경우 허용 규칙이 일치하더라도 콜백에 도달합니다. `dontAsk` 모드에서는 콜백을 호출하지 않고 이러한 호출이 거부됩니다.

54</Warning>54</Warning>

55 55 

56또한 [`PermissionRequest` 훅](/ko/agent-sdk/hooks#available-hooks)을 사용하여 Claude가 승인을 기다리고 있을 때 외부 알림(Slack, 이메일, 푸시)을 보낼 수 있습니다.56또한 [`PermissionRequest` 훅](/docs/ko/agent-sdk/hooks#available-hooks)을 사용하여 Claude가 승인을 기다리고 있을 때 외부 알림(Slack, 이메일, 푸시)을 보낼 수 있습니다.

57 57 

58<h2 id="handle-tool-approval-requests">58<h2 id="handle-tool-approval-requests">

59 도구 승인 요청 처리59 도구 승인 요청 처리

65| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |65| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

66| `toolName` | Claude가 사용하려는 도구의 이름(예: `"Bash"`, `"Write"`, `"Edit"`) |66| `toolName` | Claude가 사용하려는 도구의 이름(예: `"Bash"`, `"Write"`, `"Edit"`) |

67| `input` | Claude가 도구에 전달하는 매개변수입니다. 내용은 도구에 따라 다릅니다. |67| `input` | Claude가 도구에 전달하는 매개변수입니다. 내용은 도구에 따라 다릅니다. |

68| `options` (TS) / `context` (Python) | 선택적 `suggestions`(재프롬프트를 피하기 위한 제안된 `PermissionUpdate` 항목)과 취소 신호를 포함한 추가 컨텍스트입니다. TypeScript에서 `signal`은 `AbortSignal`입니다. Python에서 신호 필드는 향후 사용을 위해 예약되어 있습니다. Python의 경우 [`ToolPermissionContext`](/ko/agent-sdk/python#toolpermissioncontext)를 참조하십시오. |68| `options` (TS) / `context` (Python) | 선택적 `suggestions`(재프롬프트를 피하기 위한 제안된 `PermissionUpdate` 항목)과 취소 신호를 포함한 추가 컨텍스트입니다. TypeScript에서 `signal`은 `AbortSignal`입니다. Python에서 신호 필드는 향후 사용을 위해 예약되어 있습니다. Python의 경우 [`ToolPermissionContext`](/docs/ko/agent-sdk/python#toolpermissioncontext)를 참조하십시오. |

69 69 

70`input` 객체에는 도구별 매개변수가 포함됩니다. 일반적인 예:70`input` 객체에는 도구별 매개변수가 포함됩니다. 일반적인 예:

71 71 

76| `Edit` | `file_path`, `old_string`, `new_string` |76| `Edit` | `file_path`, `old_string`, `new_string` |

77| `Read` | `file_path`, `offset`, `limit` |77| `Read` | `file_path`, `offset`, `limit` |

78 78 

79완전한 입력 스키마는 SDK 참조를 참조하십시오. [Python](/ko/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/ko/agent-sdk/typescript#tool-input-types).79완전한 입력 스키마는 SDK 참조를 참조하십시오. [Python](/docs/ko/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/docs/ko/agent-sdk/typescript#tool-input-types).

80 80 

81이 정보를 사용자에게 표시하여 작업을 허용할지 거부할지 결정한 후 적절한 응답을 반환할 수 있습니다.81이 정보를 사용자에게 표시하여 작업을 허용할지 거부할지 결정한 후 적절한 응답을 반환할 수 있습니다.

82 82 

200</CodeGroup>200</CodeGroup>

201 201 

202<Note>202<Note>

203 Python에서 `can_use_tool`은 [스트리밍 모드](/ko/agent-sdk/streaming-vs-single-mode)가 필요합니다. `query(prompt=generator)` 또는 `ClaudeSDKClient.connect(prompt=async_iterable)`을 통해 유한한 메시지 스트림을 전달하면, 등록된 훅이나 프로세스 내 MCP 서버가 스트림을 열어 두지 않는 한 권한 콜백이 호출되기 전에 SDK가 입력 스트림을 닫습니다. 위의 예제는 `{"continue_": True}`를 반환하는 `PreToolUse` 훅으로 스트림을 열어 둡니다. 프롬프트 없이 연결하고 `ClaudeSDKClient.query()`를 통해 메시지를 보내면 스트림이 자동으로 열려 있으며 훅이 필요하지 않습니다.203 Python에서 `can_use_tool`은 [스트리밍 모드](/docs/ko/agent-sdk/streaming-vs-single-mode)가 필요합니다. `query(prompt=generator)` 또는 `ClaudeSDKClient.connect(prompt=async_iterable)`을 통해 유한한 메시지 스트림을 전달하면, 등록된 훅이나 프로세스 내 MCP 서버가 스트림을 열어 두지 않는 한 권한 콜백이 호출되기 전에 SDK가 입력 스트림을 닫습니다. 위의 예제는 `{"continue_": True}`를 반환하는 `PreToolUse` 훅으로 스트림을 열어 둡니다. 프롬프트 없이 연결하고 `ClaudeSDKClient.query()`를 통해 메시지를 보내면 스트림이 자동으로 열려 있으며 훅이 필요하지 않습니다.

204</Note>204</Note>

205 205 

206이 예제는 `y` 이외의 모든 입력이 거부로 처리되는 y/n 흐름을 사용합니다. 실제로는 사용자가 요청을 수정하거나, 피드백을 제공하거나, Claude를 완전히 리디렉션할 수 있는 더 풍부한 UI를 구축할 수 있습니다. 응답할 수 있는 모든 방법은 [도구 요청에 응답](#respond-to-tool-requests)을 참조하십시오.206이 예제는 `y` 이외의 모든 입력이 거부로 처리되는 y/n 흐름을 사용합니다. 실제로는 사용자가 요청을 수정하거나, 피드백을 제공하거나, Claude를 완전히 리디렉션할 수 있는 더 풍부한 UI를 구축할 수 있습니다. 응답할 수 있는 모든 방법은 [도구 요청에 응답](#respond-to-tool-requests)을 참조하십시오.

216| **허용** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` |216| **허용** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` |

217| **거부** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` |217| **거부** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` |

218 218 

219허용할 때 도구는 Claude가 요청한 입력으로 실행되며, 수정된 입력을 반환하지 않는 한 그렇습니다. TypeScript에서는 `updatedInput`, Python에서는 `updated_input`입니다. {/* min-version: 2.1.207 */}v2.1.207 이전에는 Claude Code가 `updatedInput`을 생략한 허용 결과를 거부하고 검증 오류로 도구 호출을 거부했습니다.219허용할 때 도구는 Claude가 요청한 입력으로 실행되며, 수정된 입력을 반환하지 않는 한 그렇습니다. TypeScript에서는 `updatedInput`, Python에서는 `updated_input`입니다. v2.1.207 이전에는 Claude Code가 `updatedInput`을 생략한 허용 결과를 거부하고 검증 오류로 도구 호출을 거부했습니다.

220 220 

221거부할 때 이유를 설명하는 메시지를 제공합니다. Claude는 이 메시지를 보고 접근 방식을 조정할 수 있습니다.221거부할 때 이유를 설명하는 메시지를 제공합니다. Claude는 이 메시지를 보고 접근 방식을 조정할 수 있습니다.

222 222 

247* **승인 및 기억**: 제안된 권한 규칙을 다시 에코하여 일치하는 호출이 다음 번에 프롬프트를 건너뛰도록 함247* **승인 및 기억**: 제안된 권한 규칙을 다시 에코하여 일치하는 호출이 다음 번에 프롬프트를 건너뛰도록 함

248* **거부**: 도구를 차단하고 이유를 Claude에 알림248* **거부**: 도구를 차단하고 이유를 Claude에 알림

249* **대안 제안**: 차단하지만 사용자가 원하는 것으로 Claude를 안내249* **대안 제안**: 차단하지만 사용자가 원하는 것으로 Claude를 안내

250* **완전히 리디렉션**: [스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하여 Claude에 완전히 새로운 지시를 보냄250* **완전히 리디렉션**: [스트리밍 입력](/docs/ko/agent-sdk/streaming-vs-single-mode)을 사용하여 Claude에 완전히 새로운 지시를 보냄

251 251 

252<Tabs>252<Tabs>

253 <Tab title="승인">253 <Tab title="승인">

311 </Tab>311 </Tab>

312 312 

313 <Tab title="승인 및 기억">313 <Tab title="승인 및 기억">

314 사용자가 승인하고 이런 종류의 호출에 대해 다시 묻지 않기를 원합니다. 세 번째 콜백 인수는 `suggestions`을 포함하며, 이는 준비된 [`PermissionUpdate`](/ko/agent-sdk/typescript#permissionupdate) 항목의 배열입니다. `updatedPermissions`에서 하나를 다시 에코하여 적용합니다. `localSettings` 대상이 있는 제안은 규칙을 `.claude/settings.local.json`에 작성하므로 향후 세션에서 일치하는 호출에 대한 프롬프트를 건너뜁니다.314 사용자가 승인하고 이런 종류의 호출에 대해 다시 묻지 않기를 원합니다. 세 번째 콜백 인수는 `suggestions`을 포함하며, 이는 준비된 [`PermissionUpdate`](/docs/ko/agent-sdk/typescript#permissionupdate) 항목의 배열입니다. `updatedPermissions`에서 하나를 다시 에코하여 적용합니다. `localSettings` 대상이 있는 제안은 규칙을 `.claude/settings.local.json`에 작성하므로 향후 세션에서 일치하는 호출에 대한 프롬프트를 건너뜁니다.

315 315 

316 Python 예제는 `claude-agent-sdk` 0.1.80 이상이 필요합니다.316 Python 예제는 `claude-agent-sdk` 0.1.80 이상이 필요합니다.

317 317 

415 </Tab>415 </Tab>

416 416 

417 <Tab title="완전히 리디렉션">417 <Tab title="완전히 리디렉션">

418 방향의 완전한 변경(단순한 밀어붙이기가 아닌)의 경우 [스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하여 Claude에 새로운 지시를 직접 보냅니다. 이는 현재 도구 요청을 우회하고 Claude에 완전히 새로운 지시를 따르도록 합니다.418 방향의 완전한 변경(단순한 밀어붙이기가 아닌)의 경우 [스트리밍 입력](/docs/ko/agent-sdk/streaming-vs-single-mode)을 사용하여 Claude에 새로운 지시를 직접 보냅니다. 이는 현재 도구 요청을 우회하고 Claude에 완전히 새로운 지시를 따르도록 합니다.

419 </Tab>419 </Tab>

420</Tabs>420</Tabs>

421 421 

426Claude가 여러 유효한 접근 방식이 있는 작업에 대해 더 많은 방향이 필요할 때 `AskUserQuestion` 도구를 호출합니다. 이는 `toolName`이 `AskUserQuestion`으로 설정된 `canUseTool` 콜백을 트리거합니다. 입력에는 Claude의 질문이 객관식 옵션으로 포함되어 있으며, 이를 사용자에게 표시하고 선택 사항을 반환합니다.426Claude가 여러 유효한 접근 방식이 있는 작업에 대해 더 많은 방향이 필요할 때 `AskUserQuestion` 도구를 호출합니다. 이는 `toolName`이 `AskUserQuestion`으로 설정된 `canUseTool` 콜백을 트리거합니다. 입력에는 Claude의 질문이 객관식 옵션으로 포함되어 있으며, 이를 사용자에게 표시하고 선택 사항을 반환합니다.

427 427