476| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |476| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |
477| `asyncRewake` | 아니요 | `true`이면 백그라운드에서 실행되고 종료 코드 2에서 Claude를 깨웁니다. 훅의 stderr 또는 stderr가 비어 있으면 stdout이 Claude에게 [시스템 리마인더](/docs/ko/glossary#system-reminder)로 표시되므로 장시간 실행되는 백그라운드 실패에 반응할 수 있습니다. |477| `asyncRewake` | 아니요 | `true`이면 백그라운드에서 실행되고 종료 코드 2에서 Claude를 깨웁니다. 훅의 stderr 또는 stderr가 비어 있으면 stdout이 Claude에게 [시스템 리마인더](/docs/ko/glossary#system-reminder)로 표시되므로 장시간 실행되는 백그라운드 실패에 반응할 수 있습니다. |
478| `shell` | 아니요 | 이 hook에 사용할 셸. `"bash"` 또는 `"powershell"`을 허용합니다. 기본값은 `"bash"` 또는 Git Bash가 설치되지 않은 경우 Windows에서 `"powershell"`입니다. `"powershell"`을 설정하면 Windows에서 PowerShell을 통해 명령을 실행합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 필요하지 않습니다. hook이 PowerShell을 직접 생성하기 때문입니다. `args`가 설정되면 무시됩니다. |478| `shell` | 아니요 | 이 hook에 사용할 셸. `"bash"` 또는 `"powershell"`을 허용합니다. 기본값은 `"bash"` 또는 Git Bash가 설치되지 않은 경우 Windows에서 `"powershell"`입니다. `"powershell"`을 설정하면 Windows에서 PowerShell을 통해 명령을 실행합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL`이 필요하지 않습니다. hook이 PowerShell을 직접 생성하기 때문입니다. `args`가 설정되면 무시됩니다. |
479| `onFailure` | 아니요 | 훅이 실패할 때 해당 작업에 일어나는 동작: 기본값인 `"continue"` 또는 `"block"`. [훅이 실패할 때 작업 차단](#block-the-action-when-a-hook-fails)을 참조하십시오. Claude Code v2.1.295 이상이 필요합니다. |479| `onFailure` | 아니요 | 훅이 실패할 때 훅을 트리거한 작업이 계속 진행되는지 여부: `"continue"` 또는 `"block"`. `"block"` 및 필드를 설정하지 않은 경우에 대해서는 [훅이 실패할 때 작업 차단](#block-the-action-when-a-hook-fails)을 참조하십시오. Claude Code v2.1.295 이상이 필요합니다. |
480 480
481<a id="exec-form-and-shell-form" />481<a id="exec-form-and-shell-form" />
482 482
829 829
830* **성공**: hook이 0으로 종료합니다. Claude Code는 hook이 출력한 [JSON 출력](#json-output) 필드를 적용하며, 해당 필드가 작업을 차단하거나 거부하지 않는 한 작업이 진행됩니다. 예외는 [백그라운드 프로세스를 시작하는 hook](#hooks-that-start-a-background-process)에서 다룹니다.830* **성공**: hook이 0으로 종료합니다. Claude Code는 hook이 출력한 [JSON 출력](#json-output) 필드를 적용하며, 해당 필드가 작업을 차단하거나 거부하지 않는 한 작업이 진행됩니다. 예외는 [백그라운드 프로세스를 시작하는 hook](#hooks-that-start-a-background-process)에서 다룹니다.
831* **차단 오류**: hook이 2로 종료합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 Claude Code는 작업을 중지합니다.831* **차단 오류**: hook이 2로 종료합니다. [차단할 수 있는 이벤트](#exit-code-2-behavior-per-event)에서 Claude Code는 작업을 중지합니다.
832* **차단하지 않는 오류**: hook이 그 밖의 코드로 종료하거나, 시작되지 않거나 잘못된 JSON을 출력하는 등 다른 방식으로 실패합니다. 작업은 진행되며, `PreToolUse`와 같은 이벤트에서는 트랜스크립트에 `<hook name> hook error` 알림이 표시됩니다. 실패한 hook이 작업을 차단하게 하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.832* **차단하지 않는 오류**: hook이 그 밖의 코드로 종료하거나, 시작되지 않거나 잘못된 JSON을 출력하는 등 다른 방식으로 실패합니다. 작업은 진행됩니다. 단, `onFailure`가 `"block"`으로 설정된 hook처럼 [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)은 예외입니다. `PreToolUse`와 같은 이벤트에서는 트랜스크립트에 `<hook name> hook error` 알림이 표시됩니다.
833 833
834hook이 stdout에 출력하는 내용에 따라 결과가 달라질 수 있습니다. 예를 들어 `PreToolUse` hook이 1로 종료하지만 검증을 통과하는 JSON을 출력하면 실행은 성공이며 JSON 필드가 결과를 결정합니다. `PreToolUse`와 같은 이벤트에서 hook의 결과를 확인하려면 첫 번째 열에서 stdout에 출력한 내용을, 맨 위 행에서 종료 코드를 찾아 맞춰 봅니다:834hook이 stdout에 출력하는 내용에 따라 결과가 달라질 수 있습니다. 예를 들어 `PreToolUse` hook이 1로 종료하지만 검증을 통과하는 JSON을 출력하면 해당 JSON이 여전히 결과를 결정할 수 있습니다. `PreToolUse`와 같은 이벤트에서 hook의 결과를 확인하려면 첫 번째 열에서 stdout에 출력한 내용을, 맨 위 행에서 종료 코드를 찾아 맞춰 봅니다:
835 835
836| Stdout | 종료 0 | 종료 2 | 그 밖의 종료 코드 |836| Stdout | 종료 0 | 종료 2 | 그 밖의 종료 코드 |
837| :- | :- | :- | :- |837| :- | :- | :- | :- |
838| [스키마 검증](#json-output)을 통과하는 JSON 객체 | 성공. 필드가 적용됩니다 | 차단 오류. Claude Code는 여전히 필드를 읽지만 필드가 차단을 재정의할 수는 없습니다 | 성공. Claude Code는 종료 코드를 무시하고 필드만으로 결과를 결정합니다. [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정하면 실패로 간주됩니다 |838| [스키마 검증](#json-output)을 통과하는 JSON 객체 | 성공. 필드가 적용됩니다 | 차단 오류. Claude Code는 여전히 필드를 읽지만 필드가 차단을 재정의할 수는 없습니다 | 성공. Claude Code는 종료 코드를 무시하고 필드만으로 결과를 결정합니다. [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)의 경우에는 대신 실패로 간주됩니다 |
839| [구문 분석할 수 없거나](#exit-code-0) 스키마 검증에 실패하는 JSON | 차단하지 않는 오류. 알림에 구문 분석 또는 검증 메시지가 표시됩니다 | 차단 오류. stderr이 이유가 됩니다 | 차단하지 않는 오류. 알림에 구문 분석 또는 검증 메시지가 표시됩니다 |839| [구문 분석할 수 없거나](#exit-code-0) 스키마 검증에 실패하는 JSON | 차단하지 않는 오류. 알림에 구문 분석 또는 검증 메시지가 표시됩니다 | 차단 오류. stderr이 이유가 됩니다 | 차단하지 않는 오류. 알림에 구문 분석 또는 검증 메시지가 표시됩니다 |
840| [일반 텍스트](#exit-code-0) 또는 출력 없음 | 성공 | 차단 오류. stderr이 이유가 됩니다 | 차단하지 않는 오류. 알림에 stderr의 첫 번째 줄이 표시됩니다 |840| [일반 텍스트](#exit-code-0) 또는 출력 없음 | 성공 | 차단 오류. stderr이 이유가 됩니다 | 차단하지 않는 오류. 알림에 stderr의 첫 번째 줄이 표시됩니다 |
841 841
864* **각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이며, 첫 줄이 `{`로 시작하고 마지막 줄이 `}`로 끝나는 출력**: 필드를 설정하는 JSON 출력 객체인 줄이 없으면 일반 텍스트이고, 그러한 줄이 있으면 구문 분석 실패입니다.864* **각각 자체적으로 JSON으로 구문 분석되는 두 줄 이상이며, 첫 줄이 `{`로 시작하고 마지막 줄이 `}`로 끝나는 출력**: 필드를 설정하는 JSON 출력 객체인 줄이 없으면 일반 텍스트이고, 그러한 줄이 있으면 구문 분석 실패입니다.
865* **`{`로 시작하고 `}`로 끝나지만 유효한 JSON이 아닌 그 밖의 출력**: 구문 분석 실패입니다.865* **`{`로 시작하고 `}`로 끝나지만 유효한 JSON이 아닌 그 밖의 출력**: 구문 분석 실패입니다.
866 866
867Claude Code가 stdout을 JSON으로 구문 분석하려고 시도했지만 실패하거나, 구문 분석된 객체가 [스키마 검증](#json-output)에 실패하면 실행은 [차단하지 않는 오류](#exit-code-output)가 됩니다. `<hook name> hook error` 알림에 구문 분석 또는 검증 메시지가 표시됩니다. 일반 텍스트 stdout을 컨텍스트로 추가하는 이벤트에서 Claude Code는 구문 분석에 실패한 stdout을 추가하지 않습니다.867[실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한, 구문 분석 실패 또는 [스키마 검증](#json-output)에 실패한 구문 분석된 객체는 [차단하지 않는 오류](#exit-code-output)입니다. `<hook name> hook error` 알림에 구문 분석 또는 검증 메시지가 표시됩니다. 일반 텍스트 stdout을 컨텍스트로 추가하는 이벤트에서 Claude Code는 구문 분석에 실패한 stdout을 추가하지 않습니다.
868 868
869Claude는 0으로 종료하는 hook의 stderr을 보지 못합니다. `PreToolUse`와 같은 이벤트에서 직접 읽으려면 [디버그 로깅](#debug-hooks)을 활성화합니다. `PostToolUse` 또는 `PostToolUseFailure` hook에서 Claude에 경고를 표시하려면 대신 종료 2로 나가면 도구가 이미 실행되었더라도 [Claude가 stderr을 봅니다](#exit-code-2-behavior-per-event).869Claude는 0으로 종료하는 hook의 stderr을 보지 못합니다. `PreToolUse`와 같은 이벤트에서 직접 읽으려면 [디버그 로깅](#debug-hooks)을 활성화합니다. `PostToolUse` 또는 `PostToolUseFailure` hook에서 Claude에 경고를 표시하려면 대신 종료 2로 나가면 도구가 이미 실행되었더라도 [Claude가 stderr을 봅니다](#exit-code-2-behavior-per-event).
870 870
907 다른 종료 코드907 다른 종료 코드
908</h4>908</h4>
909 909
910hook이 0 또는 2 이외의 코드로 종료하고 stdout에 일반 텍스트를 출력하거나 아무것도 출력하지 않으면 실행은 [차단하지 않는 오류](#exit-code-output)가 됩니다. 트랜스크립트에는 `Failed with non-blocking status code:`와 hook의 stderr 첫 번째 줄이 포함된 `<hook name> hook error` 알림이 표시됩니다. 예를 들어 `Bash`에 대한 `PreToolUse` hook이 stderr에 `something broke`를 출력하고 1로 종료하면 `PreToolUse:Bash hook error` 알림에 다음 줄이 표시됩니다:910[실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한, 0 또는 2 이외의 종료 코드와 함께 stdout에 일반 텍스트를 출력하거나 아무것도 출력하지 않으면 [차단하지 않는 오류](#exit-code-output)입니다. 작업이 진행되면 트랜스크립트에 `Failed with non-blocking status code:`와 hook의 stderr 첫 번째 줄이 포함된 `<hook name> hook error` 알림이 표시됩니다.
911
912예를 들어 `Bash`에 대한 `PreToolUse` hook이 stderr에 `something broke`를 출력하고 1로 종료하면 `PreToolUse:Bash hook error` 알림에 다음 줄이 표시됩니다:
911 913
912```text theme={null}914```text theme={null}
913Failed with non-blocking status code: something broke915Failed with non-blocking status code: something broke
915 917
916첫 번째 줄이 아닌 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.918첫 번째 줄이 아닌 전체 stderr을 캡처하려면 [디버그 로깅](#debug-hooks)을 활성화합니다.
917 919
918시작할 수 없는 hook도 차단하지 않는 오류입니다. 셸 형식에서 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 알림에 인터프리터의 메시지가 표시됩니다. 예: `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. 정책 hook을 설정할 때는 첫 번째 실행에서 이 알림을 확인하세요. `settings.json`의 경로에 오타가 있으면 hook이 전혀 실행되지 않습니다. 대신 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.920[실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한, 시작할 수 없는 hook도 차단하지 않는 오류입니다. 셸 형식에서 스크립트 경로가 존재하지 않거나 실행 가능하지 않으면 셸은 127과 같은 코드로 종료되고 알림에 인터프리터의 메시지가 표시됩니다. 예를 들어 스크립트 경로가 존재하지 않으면 알림에 다음과 같은 줄이 표시됩니다:
921
922```text theme={null}
923Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory
924```
925
926정책 hook을 설정할 때는 첫 번째 실행에서 이 알림을 확인하세요. `settings.json`의 경로에 오타가 있으면 hook이 전혀 실행되지 않습니다. hook을 시작할 수 없을 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.
919 927
920<Warning>928<Warning>
921 stdout에 유효한 JSON이 없으면 Claude Code는 1이 관례적인 Unix 실패 코드임에도 불구하고 종료 코드 1을 차단하지 않는 오류로 취급합니다. hook이 정책을 적용하기 위한 것이라면 `exit 2`를 사용합니다.929 1이 관례적인 Unix 실패 코드임에도 불구하고, 유효한 JSON 출력이 없는 종료 코드 1은 [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한 차단하지 않는 오류입니다. hook이 정책을 적용하기 위한 것이라면 `exit 2`를 사용합니다.
922</Warning>930</Warning>
923 931
924<h4 id="timeouts">932<h4 id="timeouts">
929 937
930[`PreModelSwitch`](#premodelswitch)에서는 타임아웃으로 취소된 hook이 모델 전환을 차단합니다. `PreToolUse`에서는 두 hook 유형이 다르게 동작합니다:938[`PreModelSwitch`](#premodelswitch)에서는 타임아웃으로 취소된 hook이 모델 전환을 차단합니다. `PreToolUse`에서는 두 hook 유형이 다르게 동작합니다:
931 939
932* 시간 초과된 `command`, `http`, `mcp_tool` hook은 도구 호출을 차단하지 않습니다. 호출은 일반 [권한 흐름](/docs/ko/permissions)을 통해 계속되므로 멈춘 hook이 게이트 역할을 할 것이라고 기대하지 마세요. `command` 또는 `http` hook이 시간 초과될 때 호출을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.940* 시간 초과된 `command`, `http`, `mcp_tool` hook은 도구 호출을 차단하지 않습니다. 단, [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)은 예외입니다. 호출은 일반 [권한 흐름](/docs/ko/permissions)을 통해 계속되므로 멈춘 hook이 게이트 역할을 할 것이라고 기대하지 마세요. `command` 또는 `http` hook이 시간 초과될 때 호출을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.
933* 타임아웃을 초과한 [Agent SDK 콜백 hook](/docs/ko/agent-sdk/hooks)은 [도구 호출을 차단합니다](#pretooluse).941* 타임아웃을 초과한 [Agent SDK 콜백 hook](/docs/ko/agent-sdk/hooks)은 [도구 호출을 차단합니다](#pretooluse).
934 942
935<h4 id="hooks-that-start-a-background-process">943<h4 id="hooks-that-start-a-background-process">
959 hook이 실패할 때 작업 차단967 hook이 실패할 때 작업 차단
960</h4>968</h4>
961 969
962대부분의 이벤트에서 hook이 실패하거나 시간 초과되어도 Claude Code는 작업을 계속 수행하므로, 경로가 잘못되었거나 스크립트가 충돌하는 정책 hook은 모든 것을 통과시킵니다. 대신 작업을 차단하려면 `command` 또는 `http` hook에 `"onFailure": "block"`을 설정합니다. 기본값은 `"continue"`입니다. Claude Code v2.1.295 이상이 필요합니다.970대부분의 이벤트에서 hook이 실패하거나 시간 초과되어도 Claude Code는 작업을 계속 수행합니다. 그러면 경로가 잘못되었거나 스크립트가 충돌하는 정책 hook은 모든 것을 통과시킵니다. 대신 작업을 차단하려면 `command` 또는 `http` hook에 `"onFailure": "block"`을 설정합니다. Claude Code v2.1.295 이상이 필요합니다.
971
972<Note>
973 Git Bash가 없는 Windows에서는 `onFailure`가 설정되지 않은 셸 형식 `PreToolUse` 또는 `PermissionRequest` 명령 hook이 실패하면 대신 [도구 호출을 차단](#failed-hooks-on-windows-without-git-bash)할 수 있습니다.
974</Note>
963 975
964`.claude/settings.json`의 이 `PreToolUse` hook은 각 Bash 명령 전에 프로젝트 스크립트를 실행하고, 스크립트가 실패하면 명령을 차단합니다:976`.claude/settings.json`의 이 `PreToolUse` hook은 각 Bash 명령 전에 프로젝트 스크립트를 실행하고, 스크립트가 실패하면 명령을 차단합니다:
965 977
1007* **`Stop`, `SubagentStop`, `TaskCompleted`, `TeammateIdle` hook**: 이러한 이벤트에서 종료 코드 2는 Claude가 계속 작업하도록 되돌려 보내며, Claude는 실행되지 않는 hook을 고칠 수 없습니다1019* **`Stop`, `SubagentStop`, `TaskCompleted`, `TeammateIdle` hook**: 이러한 이벤트에서 종료 코드 2는 Claude가 계속 작업하도록 되돌려 보내며, Claude는 실행되지 않는 hook을 고칠 수 없습니다
1008* **백그라운드 명령 hook**: [`async` 또는 `asyncRewake`](#run-hooks-in-the-background)를 설정한 명령 hook1020* **백그라운드 명령 hook**: [`async` 또는 `asyncRewake`](#run-hooks-in-the-background)를 설정한 명령 hook
1009 1021
1022<h4 id="failed-hooks-on-windows-without-git-bash">
1023 Git Bash가 없는 Windows에서 실패한 hook
1024</h4>
1025
1026차단된 도구 호출의 오류에 다음 텍스트가 포함되어 있으면 `PreToolUse` 또는 `PermissionRequest` 명령 hook이 실패하거나 시간 초과되어 호출을 차단한 것입니다:
1027
1028```text theme={null}
1029blocking because Git Bash wasn't found and this hook doesn't set "shell" to "powershell", so only exit code 0 or 2 counts as its verdict.
1030```
1031
1032`shell`이 설정되지 않은 셸 형식 hook은 Git Bash가 설치되어 있지 않으면 PowerShell에서 실행되며, Bash용으로 작성된 스크립트는 그곳에서 작성된 그대로 실행되지 않을 수 있습니다. hook에 맞는 해결 방법을 선택합니다:
1033
1034* **hook이 Bash용으로 작성된 경우**: [Git for Windows](https://git-scm.com/downloads/win)를 설치하거나, Claude Code가 찾지 못하는 위치에 Git Bash가 설치되어 있다면 [`CLAUDE_CODE_GIT_BASH_PATH`](/docs/ko/env-vars)를 설정한 다음 새 세션을 시작합니다
1035* **hook이 `.cmd` 또는 `.bat` 파일이 아닌 하나의 `.exe`를 실행하는 경우**: [exec 형식](#exec-form-and-shell-form)을 사용하도록 프로그램을 `command`에, 인수를 `args`에 넣고 [`"onFailure": "block"`](#block-the-action-when-a-hook-fails)을 추가합니다. 그러면 Claude Code는 셸 없이 프로그램을 시작합니다. `"onFailure": "block"`이 없으면 프로그램이 실패하거나, 없거나, 시간 초과될 때 호출이 진행될 수 있습니다
1036* **hook이 PowerShell용으로 작성된 경우**: hook에 `"shell": "powershell"`과 [`"onFailure": "block"`](#block-the-action-when-a-hook-fails)을 추가합니다. `"onFailure": "block"`이 없으면 hook이 여전히 실패하거나 시간 초과될 때 호출이 진행될 수 있습니다. hook이 실패한 이유를 알아보려면 [디버그 로그](#debug-hooks)를 확인합니다
1037* **hook이 실패할 때 작업이 진행되어야 하는 경우**: hook에 `"onFailure": "continue"`를 추가합니다
1038
1039이 오류를 표시하는 hook의 경우, hook이 호출을 거부하지 않는 JSON을 출력하더라도 0 또는 2 이외의 종료 코드는 [실패](#block-the-action-when-a-hook-fails)로 간주됩니다.
1040
1010<h4 id="exit-code-2-behavior-per-event">1041<h4 id="exit-code-2-behavior-per-event">
1011 이벤트별 종료 코드 2 동작1042 이벤트별 종료 코드 2 동작
1012</h4>1043</h4>
1060* **빈 본문의 2xx**: 성공, 출력 없는 종료 코드 0과 동일1091* **빈 본문의 2xx**: 성공, 출력 없는 종료 코드 0과 동일
1061* **JSON 객체 본문의 2xx**: 명령 hook과 동일한 [JSON 출력](#json-output) 스키마를 사용하여 구문 분석됩니다. 스키마 검증에 실패하는 본문은 차단하지 않는 오류입니다1092* **JSON 객체 본문의 2xx**: 명령 hook과 동일한 [JSON 출력](#json-output) 스키마를 사용하여 구문 분석됩니다. 스키마 검증에 실패하는 본문은 차단하지 않는 오류입니다
1062* **일반 텍스트 등 그 밖의 본문의 2xx**: 차단하지 않는 오류이며, 2xx가 아닌 상태와 동일하게 처리됩니다. Claude Code는 텍스트를 Claude의 컨텍스트에 추가하지 않습니다1093* **일반 텍스트 등 그 밖의 본문의 2xx**: 차단하지 않는 오류이며, 2xx가 아닌 상태와 동일하게 처리됩니다. Claude Code는 텍스트를 Claude의 컨텍스트에 추가하지 않습니다
1063* **2xx가 아닌 상태**: 차단하지 않는 오류, 실행이 계속됨1094* **2xx가 아닌 상태**: 차단하지 않는 오류
1064* **연결 실패**: 차단하지 않는 오류, 실행이 계속됨1095* **연결 실패**: 차단하지 않는 오류
1065* **타임아웃**: [타임아웃](#timeouts)에 설명된 대로 hook이 취소됩니다1096* **타임아웃**: [타임아웃](#timeouts)에 설명된 대로 hook이 취소됩니다
1066 1097
1067HTTP hook은 상태 코드만으로 차단 오류를 신호할 수 없습니다. 2xx가 아닌 상태나 실패한 연결은 [차단하지 않는 오류](#exit-code-output)입니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 결정 필드를 포함하는 JSON 본문과 함께 2xx 응답을 반환합니다. 요청이 실패하거나 2xx가 아닌 상태를 반환할 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.1098[차단하지 않는 오류](#exit-code-output) 후에는 [실패 시 작업을 차단하는 hook](#block-the-action-when-a-hook-fails)이 아닌 한 작업이 진행됩니다. 도구 호출을 차단하거나 권한을 거부하려면 적절한 [결정 필드](#decision-control)를 포함하는 JSON 본문과 함께 2xx 응답을 반환합니다. 요청이 실패하거나 2xx가 아닌 상태를 반환할 때 작업을 차단하려면 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)을 설정합니다.
1068 1099
1069<h3 id="json-output">1100<h3 id="json-output">
1070 JSON 출력1101 JSON 출력
1573}1604}
1574```1605```
1575 1606
1607프롬프트가 `/deploy staging`처럼 사용자가 입력한 [스킬](/docs/ko/skills) 또는 사용자 지정 명령인 경우, 훅은 펼쳐진 스킬 내용이 아니라 입력한 그대로의 줄을 받습니다. 훅이 프롬프트를 차단하면 명령이 실행되지 않으므로, 스킬이 [`` !`<command>` ``로 주입하는](/docs/ko/skills#inject-dynamic-context) 셸 명령도 실행되지 않습니다. 대신 명령의 이름이나 인수로 매칭하려면 [UserPromptExpansion](#userpromptexpansion)을 사용하세요.
1608
1576<h4 id="userpromptsubmit-decision-control">1609<h4 id="userpromptsubmit-decision-control">
1577 UserPromptSubmit 결정 제어1610 UserPromptSubmit 결정 제어
1578</h4>1611</h4>
2076 2109
2077| 필드 | 설명 |2110| 필드 | 설명 |
2078| :- | :- |2111| :- | :- |
2079| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다. 단, [어떤 모드에서도 자동 승인되지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves), [네트워크 경로에서의 읽기](/docs/ko/permissions#network-paths), 그리고 [`updatedInput`과 함께 사용해야 하는](#allow-with-updatedinput) `AskUserQuestion` 및 `ExitPlanMode`는 예외입니다. `"deny"`는 도구 호출을 막습니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 도구를 나중에 재개할 수 있도록 정상적으로 종료합니다. 훅이 무엇을 반환하든 [거부 및 확인 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가됩니다 |2112| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다. 단, [어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)과 [네트워크 경로에서의 읽기](/docs/ko/permissions#network-paths)는 예외입니다. `AskUserQuestion`과 `ExitPlanMode`에는 [`"allow"`와 함께 사용하는 `updatedInput`](#allow-with-updatedinput)이 필요합니다. 플랜 모드의 경우 [플랜 모드에서의 훅 승인](/docs/ko/permissions#hook-approvals-in-plan-mode)을 참조하세요. `"deny"`는 도구 호출을 막습니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 나중에 도구를 재개할 수 있도록 정상적으로 종료합니다. [거부 및 확인 규칙](/docs/ko/permissions#manage-permissions)은 훅이 무엇을 반환하든 여전히 평가됩니다 |
2080| `permissionDecisionReason` | `"ask"`의 경우 권한 프롬프트에서 사용자에게 표시됩니다. 아무도 해당 프롬프트에 답할 수 없는 `-p` 실행에서 Claude Code가 [호출을 거부](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)하면, Claude가 대신 도구 결과에서 이유를 읽습니다. `"deny"`의 경우 Claude에게 표시됩니다. `"allow"` 및 `"defer"`의 경우 [디버그 로그](#debug-hooks)에만 기록됩니다 |2113| `permissionDecisionReason` | `"ask"`의 경우 권한 프롬프트에서 사용자에게 표시됩니다. 아무도 해당 프롬프트에 답할 수 없는 `-p` 실행에서 Claude Code가 [호출을 거부](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)하면, Claude가 대신 도구 결과에서 이유를 읽습니다. `"deny"`의 경우 Claude에게 표시됩니다. `"allow"` 및 `"defer"`의 경우 [디버그 로그](#debug-hooks)에만 기록됩니다 |
2081| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 대체하므로 수정된 필드와 함께 변경되지 않은 필드도 포함하십시오. Claude Code는 권한 규칙과 Bash 명령의 [자동 백그라운드 전환 적격성](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)을 Claude가 보낸 입력이 아닌 훅이 반환한 입력을 기준으로 평가합니다. 자동 승인하려면 `"allow"`와, 수정된 입력을 사용자에게 보여주려면 `"ask"`와 함께 사용하십시오. `"defer"`의 경우 무시됩니다 |2114| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 대체하므로 수정된 필드와 함께 변경되지 않은 필드도 포함하십시오. Claude Code는 권한 규칙과 Bash 명령의 [자동 백그라운드 전환 적격성](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)을 Claude가 보낸 입력이 아닌 훅이 반환한 입력을 기준으로 평가합니다. 자동 승인하려면 `"allow"`와, 수정된 입력을 사용자에게 보여주려면 `"ask"`와 함께 사용하십시오. `"defer"`의 경우 무시됩니다 |
2082| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. `permissionDecision`이 `"defer"`일 때는 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |2115| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. `permissionDecision`이 `"defer"`일 때는 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |
3718 3751
3719Claude Code는 결정과 관계없이 훅이 반환하는 모든 `systemMessage`를 사용자에게 표시하므로, 비용 보고 훅은 `{"systemMessage": "..."}`를 반환하고 0으로 종료할 수 있습니다.3752Claude Code는 결정과 관계없이 훅이 반환하는 모든 `systemMessage`를 사용자에게 표시하므로, 비용 보고 훅은 `{"systemMessage": "..."}`를 반환하고 0으로 종료할 수 있습니다.
3720 3753
3721타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 다른 이벤트에서 타임아웃이 어떻게 동작하는지는 [타임아웃](#timeouts)을 참조하세요. 이 이벤트의 기본 타임아웃은 30초입니다. `PreModelSwitch`는 `command`, `http`, `mcp_tool` 훅만 실행하므로 `prompt`와 `agent`의 기본값은 적용되지 않습니다.3754<h4 id="premodelswitch-timeouts-and-other-exit-codes">
3755 PreModelSwitch 타임아웃 및 기타 종료 코드
3756</h4>
3757
3758타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 이 이벤트의 기본 타임아웃은 30초입니다.
3722 3759
37230이나 2가 아닌 코드로 종료하고 JSON 결정을 출력하지 않는 훅은 [기타 종료 코드](#other-exit-codes)에 설명된 대로 비차단 오류입니다.37600 또는 2가 아닌 종료 코드의 동작은 [기타 종료 코드](#other-exit-codes)를 참조하십시오.
3724 3761
3725<h3 id="postmodelswitch">3762<h3 id="postmodelswitch">
3726 PostModelSwitch3763 PostModelSwitch
