14 14
15플러그인은 Claude Code가 자체 프로세스에서 호출하는 JavaScript 함수로 훅을 등록할 수도 있으며, 이러한 함수는 이벤트에 대응할 뿐 아니라 인터페이스에 그리기도 할 수 있습니다. 이렇게 하는 플러그인을 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)라고 하며, 이러한 함수 훅은 이 페이지가 아닌 [이벤트에 반응하기](https://code.claude.com/docs/ko/plugins/mods/events.md)에서 다룹니다. 이 페이지의 훅은 mod와 함께 계속 작동합니다.15플러그인은 Claude Code가 자체 프로세스에서 호출하는 JavaScript 함수로 훅을 등록할 수도 있으며, 이러한 함수는 이벤트에 대응할 뿐 아니라 인터페이스에 그리기도 할 수 있습니다. 이렇게 하는 플러그인을 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)라고 하며, 이러한 함수 훅은 이 페이지가 아닌 [이벤트에 반응하기](https://code.claude.com/docs/ko/plugins/mods/events.md)에서 다룹니다. 이 페이지의 훅은 mod와 함께 계속 작동합니다.
16 16
17## Hook 수명 주기17## 훅 수명 주기
18 18
19Claude Code는 세션 중 특정 지점에서 hook을 실행합니다. 이벤트가 발생하고 matcher가 일치하면 Claude Code는 이벤트에 대한 JSON 컨텍스트를 hook 핸들러에 전달합니다. 명령 hook의 경우 입력은 stdin에 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다. 그러면 핸들러는 입력을 검사하고 조치를 취한 후 선택적으로 결정을 반환할 수 있습니다.19Claude Code는 세션 중 특정 시점에 훅을 실행합니다. 이벤트가 발생하고 matcher가 일치하면 Claude Code는 해당 이벤트에 대한 JSON 컨텍스트를 훅 핸들러에 전달합니다. 명령 훅의 경우 입력은 stdin으로 전달됩니다. HTTP 훅의 경우 POST 요청 본문으로 전달됩니다. 그러면 핸들러는 입력을 검사하고, 작업을 수행하고, 선택적으로 결정을 반환할 수 있습니다.
20 20
21이벤트는 세 가지 주기로 발생합니다:21이벤트는 세 가지 주기로 나뉩니다.
22 22
23* 세션당 한 번: `SessionStart` 및 `SessionEnd`23* 세션마다: `SessionStart` 및 `SessionEnd`
24* 턴당 한 번: `UserPromptSubmit`, `Stop` 및 `StopFailure`24* 턴마다: `UserPromptSubmit`, `Stop`, `StopFailure`
25* 에이전트 루프 내의 모든 도구 호출에서: `PreToolUse` 및 `PostToolUse`(단, [`EndConversation`](https://code.claude.com/docs/ko/tools-reference#endconversation-tool-behavior) 호출은 제외되며, 이는 둘 다 건너뜁니다)25* 에이전틱 루프 내부의 모든 도구 호출마다: `PreToolUse` 및 `PostToolUse`. 단, [`EndConversation`](https://code.claude.com/docs/ko/tools-reference#endconversation-tool-behavior) 호출은 둘 다 건너뜁니다
26 26
2727
28 28
29아래 표는 각 이벤트가 언제 발생하는지 요약합니다. [Hook 이벤트](#hook-events) 섹션에서는 각 이벤트의 전체 입력 스키마와 결정 제어 옵션을 문서화합니다.29아래 표는 각 이벤트가 언제 발생하는지 요약합니다. [훅 이벤트](#hook-events) 섹션에서는 각 이벤트의 전체 입력 스키마와 결정 제어 옵션을 설명합니다.
30 30
31| 이벤트 | 발생 시점 |31| 이벤트 | 발생 시점 |
32| :- | :- |32| :- | :- |
64| `ElicitationResult` | 사용자가 MCP 유도에 응답한 후, 응답이 서버로 다시 전송되기 전 |64| `ElicitationResult` | 사용자가 MCP 유도에 응답한 후, 응답이 서버로 다시 전송되기 전 |
65| `SessionEnd` | 세션이 종료될 때 |65| `SessionEnd` | 세션이 종료될 때 |
66 66
67### Hook이 어떻게 해결되는지67### 훅이 처리되는 방식
68 68
69파괴적인 셸 명령을 차단하는 이 `PreToolUse` hook을 고려하세요.69이벤트, matcher, 핸들러가 어떻게 맞물리는지 확인하기 위해 파괴적인 셸 명령을 차단하는 다음 `PreToolUse` 훅을 살펴보겠습니다.
70 70
71> [tab] macOS/Linux71> [tab] macOS/Linux
72>72>
73> `matcher`는 Bash 도구 호출로 좁혀지고 `if` 조건은 `rm *`과 일치하는 Bash 부명령으로 더 좁혀지므로 `block-rm.sh`는 두 필터가 모두 일치할 때만 생성됩니다:73> `matcher`는 대상을 Bash 도구 호출과 [Monitor 명령](#match-monitor-commands)으로 좁히고, `if` 조건은 대상을 `rm *`와 일치하는 Bash 하위 명령으로 더 좁히므로, `block-rm.sh`는 두 필터가 모두 일치할 때만 실행됩니다.
74>74>
75> ```json theme={null}75> ```json theme={null}
76> {76> {
92> }92> }
93> ```93> ```
94>94>
95> 스크립트는 stdin에서 JSON 입력을 읽고 명령을 추출한 후 `rm -rf`를 포함하면 `permissionDecision`을 `"deny"`로 반환합니다. 프로젝트의 `.claude/hooks/block-rm.sh`에 저장하고 Claude Code가 실행할 수 있도록 `chmod +x .claude/hooks/block-rm.sh`로 실행 가능하게 만듭니다:95> 이 스크립트는 stdin에서 JSON 입력을 읽고, 명령을 추출한 다음, 명령에 `rm -rf`가 포함되어 있으면 `"deny"`라는 `permissionDecision`을 반환합니다. Claude Code가 실행할 수 있도록 프로젝트의 `.claude/hooks/block-rm.sh`에 저장하고 `chmod +x .claude/hooks/block-rm.sh`로 실행 가능하게 만드십시오.
96>96>
97> ```bash theme={null}97> ```bash theme={null}
98> #!/bin/bash98> #!/bin/bash
112> fi112> fi
113> ```113> ```
114>114>
115> 이 스크립트는 이 페이지의 다른 Bash 예제처럼 JSON 입력을 파싱하므로 `jq`를 사용합니다. 따라서 이들을 시도하기 전에 `jq`를 설치하고 `PATH`에 있는지 확인하세요.115> 이 스크립트는 JSON 입력을 파싱하는 이 페이지의 다른 Bash 예제와 마찬가지로 `jq`를 사용하므로, 예제를 실행해 보기 전에 `jq`를 설치하고 `PATH`에 포함되어 있는지 확인하십시오.
116 116
117> [tab] Windows (PowerShell)117> [tab] Windows (PowerShell)
118>118>
119> matcher `Bash|PowerShell`은 [PowerShell 도구](#powershell)와 Bash를 모두 포함합니다. 단일 `if` 규칙은 한 도구의 호출만 일치하므로 각 도구는 자체 핸들러를 가집니다: 첫 번째는 `rm *`과 일치하는 Bash 부명령으로 좁혀지고, 두 번째는 `Remove-Item *`과 일치하는 PowerShell 명령으로 좁혀집니다. 둘 다 `powershell.exe`를 통해 동일한 스크립트를 실행합니다:119> matcher `Bash|PowerShell`은 Bash뿐 아니라 [PowerShell 도구](#powershell)도 포함합니다. 하나의 `if` 규칙은 하나의 도구만 지정하므로 각 도구마다 별도의 핸들러를 둡니다. 첫 번째 핸들러는 대상을 `rm *`와 일치하는 Bash 하위 명령으로, 두 번째 핸들러는 `Remove-Item *`와 일치하는 PowerShell 명령으로 좁힙니다. 두 핸들러 모두 `powershell.exe`를 통해 같은 스크립트를 실행합니다.
120>120>
121> ```json theme={null}121> ```json theme={null}
122> {122> {
156> }156> }
157> ```157> ```
158>158>
159> `-NoProfile` 플래그는 PowerShell 프로필 로드를 건너뛰므로 hook이 빠르게 시작되고, `-ExecutionPolicy Bypass`는 PowerShell이 로컬 스크립트 파일을 실행하도록 합니다.159> `-NoProfile` 플래그는 PowerShell 프로필 로드를 건너뛰어 훅이 빠르게 시작되도록 하고, `-ExecutionPolicy Bypass`는 PowerShell이 로컬 스크립트 파일을 실행할 수 있게 합니다.
160>160>
161> 스크립트는 stdin에서 JSON 입력을 읽고 명령을 추출한 후 `rm -rf` 또는 `-Recurse`가 뒤따르는 `Remove-Item`을 포함하면 `permissionDecision`을 `"deny"`로 반환합니다. 프로젝트의 `.claude/hooks/block-rm.ps1`에 저장합니다:161> 이 스크립트는 stdin에서 JSON 입력을 읽고, 명령을 추출한 다음, 명령에 `rm -rf`가 포함되어 있거나 `Remove-Item` 뒤에 `-Recurse`가 오면 `"deny"`라는 `permissionDecision`을 반환합니다. 프로젝트의 `.claude/hooks/block-rm.ps1`에 저장하십시오.
162>162>
163> ```powershell theme={null}163> ```powershell theme={null}
164> # .claude/hooks/block-rm.ps1164> # .claude/hooks/block-rm.ps1
178> }178> }
179> ```179> ```
180 180
181이제 Claude Code가 macOS/Linux 구성에 대해 `Bash "rm -rf /tmp/build"`를 실행하기로 결정했다고 가정합니다. 다음은 발생하는 일입니다:181이제 macOS/Linux 구성에서 Claude Code가 `Bash "rm -rf /tmp/build"`를 실행하기로 결정했다고 가정해 보겠습니다. 다음과 같은 일이 일어납니다.
182 182
183183
184 184
185**1. 이벤트 발생**185**1. 이벤트 발생**
186 186
187`PreToolUse` 이벤트가 발생합니다. Claude Code는 도구 입력을 stdin의 hook에 JSON으로 전송합니다:187`PreToolUse` 이벤트가 발생합니다. Claude Code는 도구 입력을 JSON 형식으로 stdin을 통해 훅에 보냅니다.
188 188
189```json theme={null}189```json theme={null}
190{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }190{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
191```191```
192 192
193**2. Matcher 확인**193**2. matcher 확인**
194 194
195matcher `"Bash"`가 도구 이름과 일치하므로 이 hook 그룹이 활성화됩니다. matcher를 생략하거나 `"*"`를 사용하면 이벤트의 모든 발생에서 그룹이 활성화됩니다.195matcher `"Bash"`가 도구 이름과 일치하므로 이 훅 그룹이 활성화됩니다. matcher를 생략하거나 `"*"`를 사용하면 해당 이벤트가 발생할 때마다 그룹이 활성화됩니다.
196 196
197**3. If 조건 확인**197**3. if 조건 확인**
198 198
199`if` 조건 `"Bash(rm *)"`은 `rm -rf /tmp/build`가 `rm *`과 일치하는 부명령이므로 일치하여 이 핸들러가 생성됩니다. 명령이 `npm test`였다면 `if` 검사가 실패하고 `block-rm.sh`는 절대 실행되지 않아 프로세스 생성 오버헤드를 피합니다. `if` 필드는 선택 사항입니다. 없으면 일치한 그룹의 모든 핸들러가 실행됩니다.199`rm -rf /tmp/build`는 `rm *`와 일치하는 하위 명령이므로 `if` 조건 `"Bash(rm *)"`가 일치하고, 이 핸들러가 실행됩니다. 명령이 `npm test`였다면 `if` 검사가 실패하여 `block-rm.sh`는 실행되지 않았을 것이며, 프로세스 생성 오버헤드를 피할 수 있습니다. `if` 필드는 선택 사항이며, 이 필드가 없으면 일치한 그룹의 모든 핸들러가 실행됩니다.
200 200
201**4. Hook 핸들러 실행**201**4. 훅 핸들러 실행**
202 202
203스크립트는 전체 명령을 검사하고 `rm -rf`를 찾으므로 stdout에 결정을 인쇄합니다:203스크립트가 전체 명령을 검사하여 `rm -rf`를 찾아내므로 stdout에 결정을 출력합니다.
204 204
205```json theme={null}205```json theme={null}
206{206{
212}212}
213```213```
214 214
215명령이 `rm file.txt`와 같은 더 안전한 `rm` 변형이었다면 스크립트는 대신 `exit 0`을 실행합니다. 출력이 없는 종료 코드 0은 hook이 보고할 결정이 없다는 의미이므로 도구 호출은 일반적인 [권한 흐름](https://code.claude.com/docs/ko/permissions.md)을 통해 계속됩니다. hook은 호출을 거부할 수 있지만 침묵을 유지하는 것은 이를 승인하지 않습니다.215명령이 `rm file.txt`처럼 더 안전한 `rm` 변형이었다면 스크립트는 대신 `exit 0`에 도달했을 것입니다. 출력 없이 종료 코드 0을 반환하면 훅이 보고할 결정이 없다는 의미이므로, 도구 호출은 일반적인 [권한 흐름](https://code.claude.com/docs/ko/permissions.md)을 따라 계속 진행됩니다. 훅은 호출을 거부할 수 있지만, 아무것도 출력하지 않는다고 해서 호출이 승인되는 것은 아닙니다.
216 216
217**5. Claude Code가 결과에 따라 행동**217**5. Claude Code가 결과에 따라 동작**
218 218
219Claude Code는 JSON 결정을 읽고 도구 호출을 차단하며 Claude에 이유를 표시합니다.219Claude Code는 JSON 결정을 읽고 도구 호출을 차단한 후 Claude에게 그 이유를 보여줍니다.
220 220
221아래 [구성](#configuration) 섹션에서는 전체 스키마를 문서화하고, 각 [hook 이벤트](#hook-events) 섹션에서는 명령이 받는 입력과 반환할 수 있는 출력을 문서화합니다.221아래 [구성](#configuration) 섹션에서는 전체 스키마를 설명하며, 각 [훅 이벤트](#hook-events) 섹션에서는 명령이 받는 입력과 반환할 수 있는 출력을 설명합니다.
222 222
223## 구성223## 구성
224 224
225Hook은 JSON 설정 파일에서 정의됩니다. 구성은 세 가지 중첩 수준을 가집니다:225Hook은 JSON 설정 파일에서 정의됩니다. 구성은 세 가지 중첩 수준을 가집니다:
226 226
2271. 응답할 [hook 이벤트](#hook-events)를 선택합니다(예: `PreToolUse` 또는 `Stop`).2271. 응답할 [hook 이벤트](#hook-events)를 선택합니다(예: `PreToolUse` 또는 `Stop`).
2282. 실행 시기를 필터링할 [matcher 그룹](#matcher-patterns)을 추가합니다(예: "Bash 도구에만 해당").2282. 실행 시점을 필터링하려면 "Bash 도구의 경우"와 같이 [matcher 그룹](#matcher-patterns)을 추가합니다
2293. 일치할 때 실행할 하나 이상의 [hook 핸들러](#hook-handler-fields)를 정의합니다.2293. 일치할 때 실행할 하나 이상의 [hook 핸들러](#hook-handler-fields)를 정의합니다.
230 230
231주석이 달린 예제를 포함한 완전한 설명은 위의 [hook이 어떻게 해결되는지](#how-a-hook-resolves)를 참조하십시오.231주석이 달린 예제를 포함한 완전한 설명은 위의 [hook이 어떻게 해결되는지](#how-a-hook-resolves)를 참조하십시오.
277| Matcher 값 | 평가 대상 | 예제 |277| Matcher 값 | 평가 대상 | 예제 |
278| :- | :- | :- |278| :- | :- | :- |
279| `"*"`, `""` 또는 생략됨 | 모두 일치 | 이벤트의 모든 발생에서 실행됨 |279| `"*"`, `""` 또는 생략됨 | 모두 일치 | 이벤트의 모든 발생에서 실행됨 |
280| 문자, 숫자, `_`, `-`, 공백, `,` 및 `\|`만 포함 | 정확한 문자열 또는 `\|` 또는 `,`로 구분된 정확한 문자열 목록(선택적 주변 공백 포함) | `Bash`는 Bash 도구만 일치합니다. `Edit\|Write` 및 `Edit, Write`는 각각 두 도구 중 하나와 정확히 일치합니다. `code-reviewer`는 해당 에이전트 유형만 일치합니다. |280| 문자, 숫자, `_`, `-`, 공백, `,` 및 `\|`만 포함 | 정확한 문자열 또는 `\|` 또는 `,`로 구분된 정확한 문자열 목록(선택적 주변 공백 포함) | `Bash`는 Bash 도구와 일치하며, `PreToolUse` 및 `PermissionRequest`에서는 [Monitor 명령](#match-monitor-commands)과도 일치합니다. `Edit\|Write` 및 `Edit, Write`는 각각 두 도구 중 하나와 정확히 일치합니다. `code-reviewer`는 해당 에이전트 유형만 일치합니다. |
281| 다른 문자 포함 | JavaScript 정규 표현식, 앵커 없음 | `^Notebook`은 이름이 `Notebook`으로 시작하는 모든 도구와 일치합니다. `mcp__memory__.*`는 `memory` 서버의 모든 도구와 일치합니다. |281| 다른 문자 포함 | JavaScript 정규 표현식, 앵커 없음 | `^Notebook`은 이름이 `Notebook`으로 시작하는 모든 도구와 일치합니다. `mcp__memory__.*`는 `memory` 서버의 모든 도구와 일치합니다. |
282 282
283정규 표현식 경로의 matcher는 JavaScript의 `RegExp.prototype.test`로 테스트되며, 값의 어디든지 일치하면 성공합니다. `Edit.*`는 `Edit`과 `NotebookEdit` 모두와 일치합니다. 전체 문자열 일치가 필요한 경우 `^Edit$`와 같이 패턴을 `^` 및 `$`로 래핑하십시오.283정규 표현식 경로의 matcher는 JavaScript의 `RegExp.prototype.test`로 테스트되며, 값의 어디든지 일치하면 성공합니다. `Edit.*`는 `Edit`과 `NotebookEdit` 모두와 일치합니다. 전체 문자열 일치가 필요한 경우 `^Edit$`와 같이 패턴을 `^` 및 `$`로 래핑하십시오.
294| `SessionStart` | 세션이 시작된 방식 | `startup`, `resume`, `clear`, `compact`, `fork` |294| `SessionStart` | 세션이 시작된 방식 | `startup`, `resume`, `clear`, `compact`, `fork` |
295| `Setup` | 설정을 트리거한 CLI 플래그 | `init`, `maintenance` |295| `Setup` | 설정을 트리거한 CLI 플래그 | `init`, `maintenance` |
296| `SessionEnd` | 세션이 종료된 이유 | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |296| `SessionEnd` | 세션이 종료된 이유 | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |
297| `Notification` | 알림 유형 | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |297| `Notification` | 알림 유형 | `permission_prompt`, `idle_prompt`, `auth_success`, `auth_storage_failure`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |
298| `SubagentStart` | 에이전트 유형 | `general-purpose`, `Explore`, `Plan`, 사용자 정의 에이전트 이름 또는 `^my-plugin:reviewer$`와 같은 플러그인 범위 이름 |298| `SubagentStart` | 에이전트 유형 | `general-purpose`, `Explore`, `Plan`, 사용자 정의 에이전트 이름 또는 `^my-plugin:reviewer$`와 같은 플러그인 범위 이름 |
299| `PreCompact`, `PostCompact` | 압축을 트리거한 항목 | `manual`, `auto` |299| `PreCompact`, `PostCompact` | 압축을 트리거한 항목 | `manual`, `auto` |
300| `PreModelSwitch`, `PostModelSwitch` | 세션이 전환되는 모델의 정규 이름([PreModelSwitch](#premodelswitch) 아래에 설명됨) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |300| `PreModelSwitch`, `PostModelSwitch` | 세션이 전환되는 모델의 정규 이름([PreModelSwitch](#premodelswitch) 아래에 설명됨) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |
385}385}
386```386```
387 387
388#### Monitor 명령 일치
389
390`Bash` matcher가 있는 [`PreToolUse`](#pretooluse) 또는 [`PermissionRequest`](#permissionrequest) hook은 Claude가 [Monitor 도구](https://code.claude.com/docs/ko/tools-reference.md#monitor-tool)로 시작하는 셸 명령에서도 실행되지만, 해당 hook의 `allow` 및 [`updatedInput`](#pretooluse-decision-control)은 이러한 명령에 영향을 주지 않습니다. Claude Code v2.1.314 이상이 필요합니다. `Bash|PowerShell`, `^Bash$`, `Bash.*`와 같은 matcher도 `Bash` matcher입니다. `Bash` matcher가 있는 hook은 [WebSocket 감시](https://code.claude.com/docs/ko/tools-reference.md#websocket-source)에 대해서는 실행되지 않으며, `Bash` matcher가 있는 `PostToolUse` hook은 Monitor에 대해 실행되지 않습니다.
391
392Monitor 명령에 대해 실행되는 hook은 해당 명령을 거부하거나 Claude Code가 사용자에게 확인을 요청하도록 할 수 있습니다. 명령을 허용하거나 다시 작성하려면 `Bash` matcher에서 Monitor를 포함하는 matcher로 전환하십시오:
393
394* **Monitor를 포함하는 matcher**: `Bash|Monitor` 또는 `.*`와 같은 matcher를 사용하거나 matcher가 없으면 hook은 Monitor 호출 자체의 입력을 받으며 `allow` 및 `updatedInput`이 적용됩니다. [`if`](#common-fields)에서는 `Monitor(tail *)`처럼 Monitor를 지정하며, 이는 [`Bash(tail *)`가 따르는 규칙](#bash-if-matching)에 따라 일치합니다. `if`에 Bash를 지정하면 hook은 여전히 Monitor 호출의 입력을 받지만 `allow` 및 `updatedInput`은 효과가 없습니다.
395* **`Bash` matcher**: hook은 Bash 호출을 받습니다. `if`에서는 `Bash(tail *)`처럼 Bash를 지정합니다. `if`에 Monitor를 지정하면 hook이 실행되지 않습니다.
396
388### Hook 핸들러 필드397### Hook 핸들러 필드
389 398
390내부 `hooks` 배열의 각 객체는 hook 핸들러입니다: matcher가 일치할 때 실행되는 셸 명령, HTTP 엔드포인트, MCP 도구, LLM 프롬프트 또는 에이전트입니다. 다섯 가지 유형이 있습니다:399내부 `hooks` 배열의 각 객체는 hook 핸들러입니다: matcher가 일치할 때 실행되는 셸 명령, HTTP 엔드포인트, MCP 도구, LLM 프롬프트 또는 에이전트입니다. 다섯 가지 유형이 있습니다:
811* **각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이며, 첫 줄이 `{`로 시작하고 마지막 줄이 `}`로 끝나는 출력**: 필드를 설정하는 JSON 출력 객체인 줄이 없으면 일반 텍스트입니다. 그러한 줄이 있으면 구문 분석 실패이므로, 해당 객체만 stdout에 출력하고 다른 내용은 출력하지 않습니다.820* **각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이며, 첫 줄이 `{`로 시작하고 마지막 줄이 `}`로 끝나는 출력**: 필드를 설정하는 JSON 출력 객체인 줄이 없으면 일반 텍스트입니다. 그러한 줄이 있으면 구문 분석 실패이므로, 해당 객체만 stdout에 출력하고 다른 내용은 출력하지 않습니다.
812* **`{`로 시작하고 `}`로 끝나지만 유효한 JSON이 아닌 그 밖의 출력**: 구문 분석 실패입니다.821* **`{`로 시작하고 `}`로 끝나지만 유효한 JSON이 아닌 그 밖의 출력**: 구문 분석 실패입니다.
813 822
814대부분의 이벤트에서 Claude Code는 stdout을 디버그 로그에 기록하고 트랜스크립트에는 표시하지 않습니다. 예외는 `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, `PostModelSwitch`이며, 여기서 Claude Code는 일반 텍스트 stdout을 Claude가 보고 활용할 수 있는 컨텍스트로 추가합니다. 이러한 이벤트에서 Claude Code는 구문 분석에 실패한 stdout을 추가하지 않습니다.823대부분의 이벤트에서 Claude Code는 stdout을 디버그 로그에 기록하고 트랜스크립트에는 표시하지 않습니다. 다음 이벤트에서는 stdout이 Claude 또는 압축 요약에 전달됩니다:
824
825* **`UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, `PostModelSwitch`**: Claude Code는 일반 텍스트 stdout을 Claude가 보고 활용할 수 있는 컨텍스트로 추가합니다. 구문 분석에 실패한 stdout은 추가하지 않습니다.
826* **`PreCompact`**: stdout이 [압축 요약에 대한 지침](#precompact-output)이 됩니다
815 827
816Claude는 0으로 종료하는 hook의 stderr을 보지 못합니다. `PreToolUse`와 같은 이벤트에서 직접 읽으려면 [디버그 로깅](#debug-hooks)을 활성화합니다. `PostToolUse` 또는 `PostToolUseFailure` hook에서 Claude에 경고를 표시하려면 대신 종료 2로 나가면 도구가 이미 실행되었더라도 [Claude가 stderr을 봅니다](#exit-code-2-behavior-per-event).828Claude는 0으로 종료하는 hook의 stderr을 보지 못합니다. `PreToolUse`와 같은 이벤트에서 직접 읽으려면 [디버그 로깅](#debug-hooks)을 활성화합니다. `PostToolUse` 또는 `PostToolUseFailure` hook에서 Claude에 경고를 표시하려면 대신 종료 2로 나가면 도구가 이미 실행되었더라도 [Claude가 stderr을 봅니다](#exit-code-2-behavior-per-event).
817 829
1050hook의 `additionalContext`, `systemMessage`, `initialUserMessage` 문자열 및 일반 stdout은 10,000자로 제한됩니다:1062hook의 `additionalContext`, `systemMessage`, `initialUserMessage` 문자열 및 일반 stdout은 10,000자로 제한됩니다:
1051 1063
1052* **범위**: Claude Code는 동일한 이벤트에 대해 여러 hook이 실행되는 경우에도 각 문자열을 개별적으로 측정합니다. JSON 출력의 경우 각 필드는 별도로 측정되며, 일반 stdout은 전체를 측정합니다.1064* **범위**: Claude Code는 동일한 이벤트에 대해 여러 hook이 실행되는 경우에도 각 문자열을 개별적으로 측정합니다. JSON 출력의 경우 각 필드는 별도로 측정되며, 일반 stdout은 전체를 측정합니다.
1053* **제한 초과**: Claude Code는 출력을 세션 디렉터리의 파일에 저장하고 파일 경로와 최대 처음 2,000자의 미리보기로 대체합니다. 큰 유효한 Bash 결과도 [출력 제한](https://code.claude.com/docs/ko/tools-reference.md#output-limits)에 설명된 대로 동일한 방식으로 처리됩니다. 해당 Bash 상한과 달리 이 제한에는 이를 높이기 위한 설정이나 환경 변수가 없습니다.1065* **제한 초과**: [PreCompact stdout](#precompact-output)을 제외하고, Claude Code는 출력을 세션 디렉터리의 파일에 저장합니다. 그리고 출력을 파일 경로와 최대 처음 2,000자의 미리보기로 대체합니다. 큰 유효한 Bash 결과도 [출력 제한](https://code.claude.com/docs/ko/tools-reference.md#output-limits)에 설명된 대로 동일한 방식으로 처리됩니다. 해당 Bash 상한과 달리 이 제한에는 이를 높이기 위한 설정이나 환경 변수가 없습니다.
1054* **파일 읽기**: Claude Code는 Claude에 파일을 읽도록 요청하지 않으므로 Claude가 항상 봐야 하는 내용은 제한 내에 유지하세요.1066* **파일 읽기**: Claude Code는 Claude에 파일을 읽도록 요청하지 않으므로 Claude가 항상 봐야 하는 내용은 제한 내에 유지하세요.
1055 1067
1056JSON 객체는 세 가지 종류의 필드를 지원합니다:1068JSON 객체는 세 가지 종류의 필드를 지원합니다:
1954 1966
1955#### PreToolUse 결정 제어1967#### PreToolUse 결정 제어
1956 1968
1957`PreToolUse` 훅은 도구 호출의 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 훅과 달리, PreToolUse는 `hookSpecificOutput` 객체 안에서 결정을 반환합니다. 이를 통해 더 풍부한 제어가 가능합니다. 네 가지 결과(허용, 거부, 확인 요청, 지연)와 함께 실행 전에 도구 입력을 수정하는 기능을 제공합니다.1969`PreToolUse` 훅은 도구 호출의 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 훅과 달리 PreToolUse는 `hookSpecificOutput` 객체 안에 결정을 반환합니다. 이를 통해 네 가지 결과(허용, 거부, 확인 요청, 지연)와 실행 전 도구 입력 수정 기능이라는 더 풍부한 제어가 가능합니다. Monitor 명령을 허용하거나 다시 작성하려면 [Monitor 명령 일치](#match-monitor-commands)를 참조하십시오.
1958 1970
1959| 필드 | 설명 |1971| 필드 | 설명 |
1960| :- | :- |1972| :- | :- |
2051 2063
2052#### 도구 호출을 나중으로 지연2064#### 도구 호출을 나중으로 지연
2053 2065
2054`"defer"`는 Agent SDK 앱이나 Claude Code 위에 구축된 사용자 지정 UI처럼 `claude -p`를 하위 프로세스로 실행하고 JSON 출력을 읽는 통합을 위한 것입니다. 이를 통해 호출 프로세스는 도구 호출에서 Claude를 일시 중지하고, 자체 인터페이스로 입력을 수집한 다음, 중단한 지점에서 재개할 수 있습니다. Claude Code는 `-p` 플래그를 사용하는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서만 이 값을 적용합니다. 대화형 세션에서는 경고를 로그에 기록하고 훅 결과를 무시합니다.2066`"defer"`는 Agent SDK 앱이나 Claude Code 위에 구축한 사용자 정의 UI처럼 `claude -p`를 하위 프로세스로 실행하고 그 JSON 출력을 읽는 통합을 위한 것입니다. 이를 통해 호출 프로세스는 도구 호출 시점에 Claude를 일시 중지하고, 자체 인터페이스로 입력을 수집한 다음, 중단한 지점에서 재개할 수 있습니다.
2067
2068Claude Code는 `-p` 플래그를 사용하는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서만, 그리고 Claude가 해당 턴에서 단일 도구 호출을 할 때만 `"defer"`를 적용합니다.
2069
2070* **대화형 세션에서**: 경고를 로그에 기록하고 훅 결과를 무시합니다
2071* **여러 도구 호출을 한 번에 하는 경우**: `"defer"`는 경고와 함께 무시되고 도구는 일반 권한 흐름을 따라 진행됩니다
2055 2072
2056`AskUserQuestion` 도구가 대표적인 사례입니다. Claude가 사용자에게 무언가를 묻고 싶지만 답할 터미널이 없는 경우입니다. `-p` 실행은 `--permission-prompt-tool`로 전달하는 MCP 도구 같은 [권한 호스트](https://code.claude.com/docs/ko/headless.md#turn-off-permission-prompts-in-unattended-runs)가 있을 때만 `AskUserQuestion`을 제공하므로, 권한 호스트와 함께 실행을 시작하십시오. 왕복 과정은 다음과 같습니다.2073`AskUserQuestion` 도구가 대표적인 사례입니다. Claude가 사용자에게 무언가를 묻고 싶지만 답할 터미널이 없는 경우입니다. `-p` 실행은 `--permission-prompt-tool`로 전달하는 MCP 도구 같은 [권한 호스트](https://code.claude.com/docs/ko/headless.md#turn-off-permission-prompts-in-unattended-runs)가 있을 때만 `AskUserQuestion`을 제공하므로, 권한 호스트와 함께 실행을 시작하십시오. 왕복 과정은 다음과 같습니다.
2057 2074
20614. 호출 프로세스가 같은 권한 호스트로 `claude -p --resume <session-id>`를 실행합니다. 같은 도구 호출이 다시 `PreToolUse`를 발생시킵니다.20784. 호출 프로세스가 같은 권한 호스트로 `claude -p --resume <session-id>`를 실행합니다. 같은 도구 호출이 다시 `PreToolUse`를 발생시킵니다.
20625. 훅이 `updatedInput`에 답변을 담아 `permissionDecision: "allow"`를 반환합니다. 도구가 실행되고 Claude가 계속 진행합니다.20795. 훅이 `updatedInput`에 답변을 담아 `permissionDecision: "allow"`를 반환합니다. 도구가 실행되고 Claude가 계속 진행합니다.
2063 2080
2064`deferred_tool_use` 필드는 도구의 `id`, `name`, `input`을 담습니다. `input`은 Claude가 도구 호출을 위해 생성한 매개변수로, 실행 전에 캡처됩니다.2081`deferred_tool_use` 필드에는 도구의 `id`, `name`, `input`이 포함됩니다.
2065 2082
2066```json theme={null}2083```json theme={null}
2067{2084{
2077}2094}
2078```2095```
2079 2096
2080타임아웃이나 재시도 제한은 없습니다. 세션은 재개할 때까지 디스크에 남아 있으며, [정리 규칙](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에 따라 기본적으로 30일 후 세션 파일을 삭제하는 [`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays) 보존 정리의 적용을 받습니다.2097타임아웃이나 재시도 횟수 제한은 없습니다. 세션은 [`cleanupPeriodDays`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays) [보존 정리](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)가 삭제할 때까지(기본값 30일) 디스크에 유지됩니다.
2081
2082재개 시 지연된 도구를 더 이상 사용할 수 없으면, 재개의 첫 결과는 `stop_reason: "tool_deferred_unavailable"`과 `is_error: true`를 가지며 훅은 발생하지 않습니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되어 있지 않을 때 발생합니다. 어떤 도구가 누락되었는지 식별할 수 있도록 `deferred_tool_use` 페이로드는 여전히 포함됩니다.
2083
2084* **재개 시 또는 재개 후에 프롬프트를 보내지 않은 경우**, 호출은 여전히 보류 중입니다. 도구를 사용할 수 있는 상태로 다시 재개하면 그 호출이 먼저 실행됩니다.
2085* **재개 시 또는 재개 후에 프롬프트를 보낸 경우**, Claude Code는 도구 결과 없이 프롬프트에 답하고 지연된 호출을 버립니다. 여전히 호출이 필요하면 도구를 사용할 수 있게 된 후 새 프롬프트를 보냅니다.
2086 2098
2087프롬프트 없이 재개할 때 기다리는 답변이 준비되지 않았다면 훅은 다시 `"defer"`를 반환할 수 있습니다. 프롬프트를 보냈는데 훅이 다시 지연하면 Claude Code는 프롬프트를 같은 방식으로 처리합니다. 즉, 도구 결과 없이 답하고 호출을 버립니다. 훅이 `"allow"` 또는 `"deny"`를 반환할 때까지 프롬프트 없이 재개하며, 이것이 호출 프로세스가 루프를 끊는 방법입니다.2099재개할 때 답변이 준비되지 않았다면 훅이 `"defer"`를 다시 반환할 수 있습니다. 그 재개와 함께 프롬프트를 보냈다면 Claude는 도구 결과 없이 프롬프트에 답하고 호출은 실행하지 않습니다. 훅이 `"allow"` 또는 `"deny"`를 반환할 때까지 프롬프트 없이 재개하십시오.
2088
2089`"defer"`는 Claude가 턴에서 단일 도구 호출을 할 때만 작동합니다. Claude가 한 번에 여러 도구 호출을 하면 `"defer"`는 경고와 함께 무시되고 도구는 일반 권한 흐름을 통해 진행됩니다. 이 제약은 재개 시 하나의 도구만 다시 실행할 수 있기 때문에 존재합니다. 나머지를 미해결 상태로 두지 않고 묶음에서 하나의 호출만 지연할 방법이 없습니다.
2090 2100
2091> [!NOTE]2101> [!NOTE]
2092>2102>
2093> 지연된 세션을 플랜 모드에서 재개하려면 Claude Code가 승인을 위해 계획을 제시할 수 있도록 `--resume`과 함께 [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 전달하십시오. 다른 조건은 [`-p`로 플랜 모드에서 재개](https://code.claude.com/docs/ko/sessions#resume-in-plan-mode-with-p)를 참조하십시오. Claude Code v2.1.246 이상이 필요합니다.2103> 지연된 세션을 플랜 모드에서 재개하려면 Claude Code가 승인을 위해 계획을 제시할 수 있도록 `--resume`과 함께 [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 전달하십시오. 다른 조건은 [`-p`로 플랜 모드에서 재개](https://code.claude.com/docs/ko/sessions#resume-in-plan-mode-with-p)를 참조하십시오. Claude Code v2.1.246 이상이 필요합니다.
2094>2104>
2095> `-p`로 재개하면 Claude Code는 저장된 다른 권한 모드를 복원하지 않습니다. 새 `claude -p` 실행이 시작될 권한 모드로 실행을 시작하므로, 지연된 세션이 `--permission-mode` 또는 `--dangerously-skip-permissions`를 사용했다면 다시 전달하십시오. `-p` 없이 `claude --resume <session-id>`로 재개하면 Claude Code는 [재개 시 권한 모드](https://code.claude.com/docs/ko/sessions.md#permission-mode-on-resume)에 나열된 예외를 제외하고 저장된 권한 모드를 복원합니다.2105> `-p`로 재개하면 Claude Code는 저장된 다른 권한 모드를 복원하지 않습니다. 새 `claude -p` 실행이 시작되는 권한 모드로 실행을 시작하므로, 연기된 세션에서 `--permission-mode` 또는 `--dangerously-skip-permissions`를 사용했다면 다시 전달하십시오.
2106
2107##### 연기된 도구를 사용할 수 없을 때 재개하기
2108
2109`stop_reason: "tool_deferred_unavailable"`이 포함된 결과는 연기된 호출의 도구를 재개된 세션에서 사용할 수 없다는 의미입니다. 예를 들어 해당 MCP 서버가 연결되지 않은 경우입니다. `PreToolUse` 훅은 실행되지 않으며, 결과의 `deferred_tool_use` 필드가 해당 도구를 알려 줍니다.
2110
2111호출이 대기 중인 동안에는 보내는 프롬프트가 Claude에 전달되지 않고 실행은 종료 코드 1로 끝납니다. `result` 필드는 `<tool> isn't available, so its deferred call didn't run.`으로 시작합니다. 호출을 실행하거나, 실행되지 않도록 삭제하십시오.
2112
2113* **호출을 실행하려면**: 도구를 사용할 수 있게 한 뒤 다시 재개합니다.
2114* **호출을 삭제하려면**: [`CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL`](https://code.claude.com/docs/ko/env-vars#variables)을 `1`로 설정하고 프롬프트와 함께 재개합니다. Claude는 호출 결과로 오류를 받고 프롬프트에 답합니다. 이후 재개할 때는 대기 중인 호출이 없습니다.
2115
2116호출을 삭제하면 실행은 빈 `result` 필드가 있는 `tool_deferred_unavailable` 결과를 기록한 다음, 두 번째 결과에 Claude의 답변을 기록합니다. 그 답변이 오류가 아니라면 종료 코드 0으로 종료됩니다. 변수를 설정하고 프롬프트를 보내지 않으면 실행은 여전히 호출을 삭제하지만 종료 코드 1로 종료됩니다.
2117
2118v2.1.319 이전에는 Claude Code가 도구 결과 없이 프롬프트에 답하고 호출을 삭제했습니다. 해당 버전에서는 도구를 사용할 수 있게 된 후 새 프롬프트를 보내십시오.
2096 2119
2097### PermissionRequest2120### PermissionRequest
2098 2121
2148| `message` | `"deny"` 전용: 권한이 거부된 이유를 Claude에게 알립니다 |2171| `message` | `"deny"` 전용: 권한이 거부된 이유를 Claude에게 알립니다 |
2149| `interrupt` | `"deny"` 전용: `true`이면 Claude를 중지합니다 |2172| `interrupt` | `"deny"` 전용: `true`이면 Claude를 중지합니다 |
2150 2173
2174Monitor 명령을 허용하거나 다시 작성하려면 [Monitor 명령 매칭하기](#match-monitor-commands)를 참조하십시오.
2175
2151`decision` 객체 없이 종료 코드 2로 종료하는 훅은 권한 흐름을 변경하지 않으며, 해당 stderr는 버려집니다. 요청을 허용하거나 거부하려면 `decision` 객체를 반환하십시오.2176`decision` 객체 없이 종료 코드 2로 종료하는 훅은 권한 흐름을 변경하지 않으며, 해당 stderr는 버려집니다. 요청을 허용하거나 거부하려면 `decision` 객체를 반환하십시오.
2152 2177
2153```json theme={null}2178```json theme={null}
2205* 모든 도구가 성공적으로 완료된 후 훅을 실행하려면 `matcher`를 생략하거나 `"*"`로 설정합니다. 그러면 훅이 직접 무엇이 변경되었는지 파악할 수 있습니다. 예를 들어 `git status --porcelain`을 실행하면 `git diff`가 놓치는 추적되지 않는 파일도 나열됩니다. 실패한 도구 호출의 경우 동일한 훅을 [PostToolUseFailure](#posttoolusefailure) 아래에 추가하십시오.2230* 모든 도구가 성공적으로 완료된 후 훅을 실행하려면 `matcher`를 생략하거나 `"*"`로 설정합니다. 그러면 훅이 직접 무엇이 변경되었는지 파악할 수 있습니다. 예를 들어 `git status --porcelain`을 실행하면 `git diff`가 놓치는 추적되지 않는 파일도 나열됩니다. 실패한 도구 호출의 경우 동일한 훅을 [PostToolUseFailure](#posttoolusefailure) 아래에 추가하십시오.
2206* 무엇이 기록했는지와 관계없이 특정 파일이 디스크에서 변경될 때 훅을 실행하려면 [FileChanged](#filechanged)를 사용하십시오. `Bash` 명령이나 Claude Code 외부의 프로세스가 동일한 파일을 다시 쓰는 경우 Claude Code는 `Edit|Write`와 일치하는 `PostToolUse` 훅을 실행하지 않습니다.2231* 무엇이 기록했는지와 관계없이 특정 파일이 디스크에서 변경될 때 훅을 실행하려면 [FileChanged](#filechanged)를 사용하십시오. `Bash` 명령이나 Claude Code 외부의 프로세스가 동일한 파일을 다시 쓰는 경우 Claude Code는 `Edit|Write`와 일치하는 `PostToolUse` 훅을 실행하지 않습니다.
2207 2232
2233#### 중단 후 PostToolUse
2234
2235도구 호출 중에 메시지를 보내거나 중단한 후 `PostToolUse` 훅이 일찍 멈춘다면, `Ctrl+Enter`, `Enter`, `Esc` 중 어느 것을 눌렀는지 확인하십시오.
2236
2237* **`Ctrl+Enter`**: 도구가 실행 중일 때 이 키를 눌러 [턴이 종료되고](https://code.claude.com/docs/ko/interactive-mode.md#when-claude-code-sends-what-you-queued) 도구가 완료되면, `PostToolUse` 훅이 그 결과에 대해 실행되며 완료까지 10초가 주어집니다. 메시지 앞에 `!` 명령을 대기열에 넣었거나, 예를 들어 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/ko/env-vars#variables)로 백그라운드 작업이 비활성화된 경우 이 키는 `Esc`처럼 동작합니다.
2238* **`Enter`**: `Enter`로 대기열에 넣은 메시지는 턴을 중단하지 않으므로 훅은 평소의 `timeout`을 유지합니다.
2239* **`Esc`**: 훅이 즉시 취소되므로, 훅이 실행되어야 할 때는 `Enter` 또는 `Ctrl+Enter`로 메시지를 보내십시오.
2240
224110초가 지나면 Claude Code는 [`timeout`](#common-fields)과 관계없이 아직 실행 중인 명령 훅을 종료합니다. 더 오래 걸리는 명령 훅이 완료되도록 하려면 [`async: true`](#run-hooks-in-the-background)로 실행하십시오. 이 경우 훅은 결과를 차단하거나 다시 작성할 수 없습니다.
2242
2243v2.1.319 이전에는 메시지로 턴을 중단한 후 훅이 시작되지 않았고, 실행 중인 훅은 중지되었습니다.
2244
2208#### PostToolUse 입력2245#### PostToolUse 입력
2209 2246
2210`PostToolUse` 훅은 도구가 이미 성공적으로 실행된 후에 발생합니다. 입력에는 도구에 전송된 인수인 `tool_input`과 도구가 반환한 결과인 `tool_response`가 모두 포함됩니다. 두 항목의 정확한 스키마는 도구에 따라 다릅니다. 파일 도구의 `tool_input` 경로는 [PreToolUse](#pretooluse-input)와 동일한 형식으로 전달됩니다. 즉 항상 절대 경로이며 플랫폼 고유의 구분자를 사용하므로 Windows에서는 백슬래시입니다. MCP 도구의 경우 입력에 [`mcp_server`](#pretooluse-input) 객체도 포함됩니다.2247`PostToolUse` 훅은 도구가 이미 성공적으로 실행된 후에 발생합니다. 입력에는 도구에 전송된 인수인 `tool_input`과 도구가 반환한 결과인 `tool_response`가 모두 포함됩니다. 두 항목의 정확한 스키마는 도구에 따라 다릅니다. 파일 도구의 `tool_input` 경로는 [PreToolUse](#pretooluse-input)와 동일한 형식으로 전달됩니다. 즉 항상 절대 경로이며 플랫폼 고유의 구분자를 사용하므로 Windows에서는 백슬래시입니다. MCP 도구의 경우 입력에 [`mcp_server`](#pretooluse-input) 객체도 포함됩니다.
2479| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 처리된 명령의 [네트워크 요청](https://code.claude.com/docs/ko/sandboxing.md#network-isolation)에 대한 사용자 승인이 필요하며, 프롬프트가 약 6초간 대기한 경우 |2516| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 처리된 명령의 [네트워크 요청](https://code.claude.com/docs/ko/sandboxing.md#network-isolation)에 대한 사용자 승인이 필요하며, 프롬프트가 약 6초간 대기한 경우 |
2480| `idle_prompt` | Claude가 약 60초 전에 응답을 마쳤고 그 이후 사용자가 입력하지 않은 경우 |2517| `idle_prompt` | Claude가 약 60초 전에 응답을 마쳤고 그 이후 사용자가 입력하지 않은 경우 |
2481| `auth_success` | 인증이 완료된 경우 |2518| `auth_success` | 인증이 완료된 경우 |
2519| `auth_storage_failure` | 로그인은 완료되었지만 Claude Code가 새 자격 증명을 [자격 증명 저장소](https://code.claude.com/docs/ko/authentication.md#credential-management)에 저장할 수 없는 경우. `auth_success` 대신 실행됩니다 |
2482| `elicitation_dialog` | MCP 서버가 elicitation 양식을 열고 사용자가 약 6초간 입력하지 않은 경우 |2520| `elicitation_dialog` | MCP 서버가 elicitation 양식을 열고 사용자가 약 6초간 입력하지 않은 경우 |
2483| `elicitation_url_dialog` | MCP 서버가 브라우저 URL을 열도록 요청하고 사용자가 약 6초간 입력하지 않은 경우 |2521| `elicitation_url_dialog` | MCP 서버가 브라우저 URL을 열도록 요청하고 사용자가 약 6초간 입력하지 않은 경우 |
2484| `elicitation_complete` | MCP 서버가 [URL 모드 elicitation](#elicitation-input)이 완료되었다고 보고한 경우 |2522| `elicitation_complete` | MCP 서버가 [URL 모드 elicitation](#elicitation-input)이 완료되었다고 보고한 경우 |
2490| `quota_auto_resume_disabled` | Claude Code가 작업을 계속하지 않고 claude.ai 사용 한도 대기를 종료한 경우: Claude Code가 스스로 시작한 대기 중에 [`autoContinueAtUsageLimit`](https://code.claude.com/docs/ko/settings-reference#autocontinueatusagelimit)이 꺼졌거나 재설정 시점이 24시간 이상 뒤로 밀린 경우, 계속한 작업이 계속 한도에 도달한 경우, 또는 계속 진행이 모델에 도달하기 전에 차단된 경우입니다. 사용자가 `Esc` 또는 `Ctrl+C`를 누르거나 **Don't continue automatically**를 선택한 경우에는 발생하지 않습니다 |2528| `quota_auto_resume_disabled` | Claude Code가 작업을 계속하지 않고 claude.ai 사용 한도 대기를 종료한 경우: Claude Code가 스스로 시작한 대기 중에 [`autoContinueAtUsageLimit`](https://code.claude.com/docs/ko/settings-reference#autocontinueatusagelimit)이 꺼졌거나 재설정 시점이 24시간 이상 뒤로 밀린 경우, 계속한 작업이 계속 한도에 도달한 경우, 또는 계속 진행이 모델에 도달하기 전에 차단된 경우입니다. 사용자가 `Esc` 또는 `Ctrl+C`를 누르거나 **Don't continue automatically**를 선택한 경우에는 발생하지 않습니다 |
2491| `plugin_notification` | [mod](https://code.claude.com/docs/ko/plugins/mods/api.md#show-something-without-starting-a-turn)가 `$.ui.notify`로 알림을 발생시킨 경우. mod가 설정하지 않는 한 훅의 `title`은 mod의 이름입니다 |2529| `plugin_notification` | [mod](https://code.claude.com/docs/ko/plugins/mods/api.md#show-something-without-starting-a-turn)가 `$.ui.notify`로 알림을 발생시킨 경우. mod가 설정하지 않는 한 훅의 `title`은 mod의 이름입니다 |
2492 2530
2493`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` 유형은 Claude Code v2.1.234 이상이 필요합니다.2531`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` 유형은 Claude Code v2.1.234 이상이 필요합니다. `auth_storage_failure` 유형은 v2.1.288 이상이 필요합니다.
2494 2532
2495터미널 세션에서 샌드박스 처리된 명령의 네트워크 요청에 대한 `permission_prompt`는 Claude Code v2.1.246 이상이 필요합니다.2533터미널 세션에서 샌드박스 처리된 명령의 네트워크 요청에 대한 `permission_prompt`는 Claude Code v2.1.246 이상이 필요합니다.
2496 2534
3326}3364}
3327```3365```
3328 3366
3367#### PreCompact 출력
3368
3369PreCompact 훅이 0으로 종료하고 차단하지 않으면, Claude Code는 해당 stdout을 압축 요약에 대한 지침으로 사용합니다. 이 stdout은 훅당 10,000자 미만으로 유지하세요. Claude Code는 더 긴 출력을 상한에서 자르고 표시를 덧붙입니다.
3370
3329### PostCompact3371### PostCompact
3330 3372
3331Claude Code가 압축 작업을 완료한 후 실행됩니다. 이 이벤트를 사용하여 새로 압축된 상태에 대응할 수 있습니다. 예를 들어 생성된 요약을 로그에 기록하거나 외부 상태를 업데이트할 수 있습니다. Claude Code는 PostCompact 훅의 `systemMessage`와 `continue` 필드를 무시합니다.3373Claude Code가 압축 작업을 완료한 후 실행됩니다. 이 이벤트를 사용하여 새로 압축된 상태에 대응할 수 있습니다. 예를 들어 생성된 요약을 로그에 기록하거나 외부 상태를 업데이트할 수 있습니다. Claude Code는 PostCompact 훅의 `systemMessage`와 `continue` 필드를 무시합니다.
