35아래 표는 각 이벤트가 언제 발생하는지 요약합니다. [Hook 이벤트](#hook-events) 섹션에서는 각 이벤트의 전체 입력 스키마와 결정 제어 옵션을 문서화합니다.35아래 표는 각 이벤트가 언제 발생하는지 요약합니다. [Hook 이벤트](#hook-events) 섹션에서는 각 이벤트의 전체 입력 스키마와 결정 제어 옵션을 문서화합니다.
36 36
37| 이벤트 | 발생 시점 |37| 이벤트 | 발생 시점 |
38| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |38| :- | :- |
39| `SessionStart` | 세션이 시작되거나 재개될 때 |39| `SessionStart` | 세션이 시작되거나 재개될 때 |
40| `Setup` | `--init-only`로 Claude Code를 시작하거나, `-p` 모드에서 `--init` 또는 `--maintenance`로 시작할 때. CI 또는 스크립트에서 일회성 준비를 위함 |40| `Setup` | `--init-only`로 Claude Code를 시작하거나, `-p` 모드에서 `--init` 또는 `--maintenance`로 시작할 때. CI 또는 스크립트에서 일회성 준비를 위함 |
41| `UserPromptSubmit` | 프롬프트를 제출할 때, Claude가 처리하기 전 |41| `UserPromptSubmit` | 프롬프트를 제출할 때, Claude가 처리하기 전 |
259hook을 정의하는 위치에 따라 범위가 결정됩니다:259hook을 정의하는 위치에 따라 범위가 결정됩니다:
260 260
261| 위치 | 범위 | 공유 가능 |261| 위치 | 범위 | 공유 가능 |
262| :------------------------------------- | :---------------------------------------------------------------------- | :------------------------------------- |262| :- | :- | :- |
263| `~/.claude/settings.json` | 모든 프로젝트 | 아니요, 로컬 머신에만 해당 |263| `~/.claude/settings.json` | 모든 프로젝트 | 아니요, 로컬 머신에만 해당 |
264| `.claude/settings.json` | 단일 프로젝트 | 예, 리포지토리에 커밋 가능 |264| `.claude/settings.json` | 단일 프로젝트 | 예, 리포지토리에 커밋 가능 |
265| `.claude/settings.local.json` | 단일 프로젝트 | 아니요, Claude Code가 설정을 저장할 때 gitignored |265| `.claude/settings.local.json` | 단일 프로젝트 | 아니요, Claude Code가 설정을 저장할 때 gitignored |
297`matcher` 필드는 hook이 실행되는 시기를 필터링합니다. matcher가 평가되는 방식은 포함된 문자에 따라 다릅니다:297`matcher` 필드는 hook이 실행되는 시기를 필터링합니다. matcher가 평가되는 방식은 포함된 문자에 따라 다릅니다:
298 298
299| Matcher 값 | 평가 대상 | 예제 |299| Matcher 값 | 평가 대상 | 예제 |
300| :----------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |300| :- | :- | :- |
301| `"*"`, `""` 또는 생략됨 | 모두 일치 | 이벤트의 모든 발생에서 실행됨 |301| `"*"`, `""` 또는 생략됨 | 모두 일치 | 이벤트의 모든 발생에서 실행됨 |
302| 문자, 숫자, `_`, `-`, 공백, `,` 및 `\|`만 포함 | 정확한 문자열 또는 `\|` 또는 `,`로 구분된 정확한 문자열 목록(선택적 주변 공백 포함) | `Bash`는 Bash 도구만 일치합니다. `Edit\|Write` 및 `Edit, Write`는 각각 두 도구 중 하나와 정확히 일치합니다. `code-reviewer`는 해당 에이전트 유형만 일치합니다. |302| 문자, 숫자, `_`, `-`, 공백, `,` 및 `\|`만 포함 | 정확한 문자열 또는 `\|` 또는 `,`로 구분된 정확한 문자열 목록(선택적 주변 공백 포함) | `Bash`는 Bash 도구만 일치합니다. `Edit\|Write` 및 `Edit, Write`는 각각 두 도구 중 하나와 정확히 일치합니다. `code-reviewer`는 해당 에이전트 유형만 일치합니다. |
303| 다른 문자 포함 | JavaScript 정규 표현식, 앵커 없음 | `^Notebook`은 이름이 `Notebook`으로 시작하는 모든 도구와 일치합니다. `mcp__memory__.*`는 `memory` 서버의 모든 도구와 일치합니다. |303| 다른 문자 포함 | JavaScript 정규 표현식, 앵커 없음 | `^Notebook`은 이름이 `Notebook`으로 시작하는 모든 도구와 일치합니다. `mcp__memory__.*`는 `memory` 서버의 모든 도구와 일치합니다. |
315각 이벤트 유형은 다른 필드에서 일치합니다:315각 이벤트 유형은 다른 필드에서 일치합니다:
316 316
317| 이벤트 | Matcher가 필터링하는 항목 | 예제 matcher 값 |317| 이벤트 | Matcher가 필터링하는 항목 | 예제 matcher 값 |
318| :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |318| :- | :- | :- |
319| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | 도구 이름 | `Bash`, `Edit\|Write`, `mcp__.*` |319| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | 도구 이름 | `Bash`, `Edit\|Write`, `mcp__.*` |
320| `SessionStart` | 세션이 시작된 방식 | `startup`, `resume`, `clear`, `compact`, `fork` |320| `SessionStart` | 세션이 시작된 방식 | `startup`, `resume`, `clear`, `compact`, `fork` |
321| `Setup` | 설정을 트리거한 CLI 플래그 | `init`, `maintenance` |321| `Setup` | 설정을 트리거한 CLI 플래그 | `init`, `maintenance` |
440이 필드는 모든 hook 유형에 적용됩니다:440이 필드는 모든 hook 유형에 적용됩니다:
441 441
442| 필드 | 필수 | 설명 |442| 필드 | 필수 | 설명 |
443| :-------------- | :-- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |443| :- | :- | :- |
444| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |444| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |
445| `if` | 아니요 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 이 hook이 실행되는 시기를 필터링하는 권한 규칙 구문. hook 명령은 도구 호출이 패턴과 일치하는 경우에만 실행됩니다. Bash 패턴이 하위 명령, `$()` 및 백틱에 대해 평가되는 방식에 대해서는 아래의 [Bash 일치 테이블](#bash-if-matching)을 참조하십시오. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` 및 `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 실행되지 않습니다. [권한 규칙](/docs/ko/permissions)과 동일한 구문을 사용합니다. |445| `if` | 아니요 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 이 hook이 실행되는 시기를 필터링하는 권한 규칙 구문. hook 명령은 도구 호출이 패턴과 일치하는 경우에만 실행됩니다. Bash 패턴이 하위 명령, `$()` 및 백틱에 대해 평가되는 방식에 대해서는 아래의 [Bash 일치 테이블](#bash-if-matching)을 참조하십시오. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` 및 `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 실행되지 않습니다. [권한 규칙](/docs/ko/permissions)과 동일한 구문을 사용합니다. |
446| `timeout` | 아니요 | 취소하기 전 초 단위. Claude Code는 [`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook에 적용하지 않습니다. 기본값: `command`, `http` 및 `mcp_tool`의 경우 600, `prompt`의 경우 30, `agent`의 경우 60. Claude Code는 [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch) 및 [`PostModelSwitch`](#postmodelswitch)에서 `command`, `http` 및 `mcp_tool` 기본값을 30으로 낮추고, [`MessageDisplay`](#messagedisplay)에서 10으로 낮춥니다. [`SessionEnd`](#sessionend) hook은 1.5초 예산을 공유합니다. 설정이 더 긴 hook별 `timeout`을 설정하면 Claude Code는 예산을 일치하도록 올립니다(최대 60초). |446| `timeout` | 아니요 | 취소하기 전 초 단위. Claude Code는 [`async: true`](#run-hooks-in-the-background)로 실행하는 명령 hook에 적용하지 않습니다. 기본값: `command`, `http` 및 `mcp_tool`의 경우 600, `prompt`의 경우 30, `agent`의 경우 60. Claude Code는 [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch) 및 [`PostModelSwitch`](#postmodelswitch)에서 `command`, `http` 및 `mcp_tool` 기본값을 30으로 낮추고, [`MessageDisplay`](#messagedisplay)에서 10으로 낮춥니다. [`SessionEnd`](#sessionend) hook은 1.5초 예산을 공유합니다. 설정이 더 긴 hook별 `timeout`을 설정하면 Claude Code는 예산을 일치하도록 올립니다(최대 60초). |
454<span id="bash-if-matching" />Bash 패턴의 경우 hook 명령이 실행되는지 여부는 패턴의 형태와 Claude가 호출하는 Bash 명령에 따라 다릅니다. 선행 `VAR=value` 할당은 일치하기 전에 제거됩니다.454<span id="bash-if-matching" />Bash 패턴의 경우 hook 명령이 실행되는지 여부는 패턴의 형태와 Claude가 호출하는 Bash 명령에 따라 다릅니다. 선행 `VAR=value` 할당은 일치하기 전에 제거됩니다.
455 455
456| `if` 패턴 | Bash 명령 | Hook 실행? | 이유 |456| `if` 패턴 | Bash 명령 | Hook 실행? | 이유 |
457| :----------------- | :-------------------------- | :------- | :------------------------------------------------------------------ |457| :- | :- | :- | :- |
458| `Bash(git *)` | `FOO=bar git push` | 예 | 선행 할당이 제거됨; `git push`가 일치함 |458| `Bash(git *)` | `FOO=bar git push` | 예 | 선행 할당이 제거됨; `git push`가 일치함 |
459| `Bash(git *)` | `npm test && git push` | 예 | 각 하위 명령이 확인됨; `git push`가 일치함 |459| `Bash(git *)` | `npm test && git push` | 예 | 각 하위 명령이 확인됨; `git push`가 일치함 |
460| `Bash(rm *)` | `echo $(rm -rf /)` | 예 | `$()` 및 백틱 내의 명령이 확인됨; `rm -rf /`가 일치함 |460| `Bash(rm *)` | `echo $(rm -rf /)` | 예 | `$()` 및 백틱 내의 명령이 확인됨; `rm -rf /`가 일치함 |
472[공통 필드](#common-fields) 외에도 명령 hook은 다음 필드를 허용합니다:472[공통 필드](#common-fields) 외에도 명령 hook은 다음 필드를 허용합니다:
473 473
474| 필드 | 필수 | 설명 |474| 필드 | 필수 | 설명 |
475| :------------ | :-- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |475| :- | :- | :- |
476| `command` | 예 | 실행할 셸 명령. `args`를 사용하면 직접 생성할 실행 파일입니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |476| `command` | 예 | 실행할 셸 명령. `args`를 사용하면 직접 생성할 실행 파일입니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |
477| `args` | 아니요 | 인수 목록. 존재하면 `command`는 실행 파일로 해결되고 `args`를 인수 벡터로 하여 직접 생성되며, 셸이 관여하지 않습니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |477| `args` | 아니요 | 인수 목록. 존재하면 `command`는 실행 파일로 해결되고 `args`를 인수 벡터로 하여 직접 생성되며, 셸이 관여하지 않습니다. [Exec 형식 및 셸 형식](#exec-form-and-shell-form) 참조 |
478| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |478| `async` | 아니요 | `true`이면 차단하지 않고 백그라운드에서 실행됩니다. [백그라운드에서 hook 실행](#run-hooks-in-the-background) 참조 |
531[공통 필드](#common-fields) 외에도 HTTP hook은 다음 필드를 허용합니다:531[공통 필드](#common-fields) 외에도 HTTP hook은 다음 필드를 허용합니다:
532 532
533| 필드 | 필수 | 설명 |533| 필드 | 필수 | 설명 |
534| :--------------- | :-- | :------------------------------------------------------------------------------------------------------------ |534| :- | :- | :- |
535| `url` | 예 | POST 요청을 보낼 URL |535| `url` | 예 | POST 요청을 보낼 URL |
536| `headers` | 아니요 | 키-값 쌍으로 추가 HTTP 헤더. 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars`에 나열된 변수만 해결됩니다. |536| `headers` | 아니요 | 키-값 쌍으로 추가 HTTP 헤더. 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars`에 나열된 변수만 해결됩니다. |
537| `allowedEnvVars` | 아니요 | 헤더 값에 보간될 수 있는 환경 변수 이름 목록. 나열되지 않은 변수에 대한 참조는 빈 문자열로 바뀝니다. 환경 변수 보간이 작동하려면 필수입니다. |537| `allowedEnvVars` | 아니요 | 헤더 값에 보간될 수 있는 환경 변수 이름 목록. 나열되지 않은 변수에 대한 참조는 빈 문자열로 바뀝니다. 환경 변수 보간이 작동하려면 필수입니다. |
572[공통 필드](#common-fields) 외에도 MCP 도구 hook은 다음 필드를 허용합니다:572[공통 필드](#common-fields) 외에도 MCP 도구 hook은 다음 필드를 허용합니다:
573 573
574| 필드 | 필수 | 설명 |574| 필드 | 필수 | 설명 |
575| :------- | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |575| :- | :- | :- |
576| `server` | 예 | 구성된 MCP 서버의 이름. [플러그인 번들 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 경우 `plugin:my-plugin:db`와 같은 범위 지정 이름 `plugin:<plugin-name>:<server-name>`입니다. 베어 서버 키가 아닙니다. 서버는 이미 연결되어 있어야 합니다. hook은 OAuth 또는 연결 흐름을 트리거하지 않습니다. |576| `server` | 예 | 구성된 MCP 서버의 이름. [플러그인 번들 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 경우 `plugin:my-plugin:db`와 같은 범위 지정 이름 `plugin:<plugin-name>:<server-name>`입니다. 베어 서버 키가 아닙니다. 서버는 이미 연결되어 있어야 합니다. hook은 OAuth 또는 연결 흐름을 트리거하지 않습니다. |
577| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |577| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |
578| `input` | 아니요 | 도구에 전달된 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 대체를 지원합니다. 예를 들어 `"${tool_input.file_path}"` |578| `input` | 아니요 | 도구에 전달된 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 대체를 지원합니다. 예를 들어 `"${tool_input.file_path}"` |
636[공통 필드](#common-fields) 외에도 프롬프트 및 에이전트 hook은 다음 필드를 허용합니다:636[공통 필드](#common-fields) 외에도 프롬프트 및 에이전트 hook은 다음 필드를 허용합니다:
637 637
638| 필드 | 필수 | 설명 |638| 필드 | 필수 | 설명 |
639| :------- | :-- | :------------------------------------------------------------------------------------------------------------------------ |639| :- | :- | :- |
640| `prompt` | 예 | 모델로 보낼 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS`를 사용합니다. 리터럴 텍스트를 포함하려면 백슬래시로 이스케이프합니다: `\$1.00`은 `$1.00`으로 렌더링됩니다. |640| `prompt` | 예 | 모델로 보낼 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS`를 사용합니다. 리터럴 텍스트를 포함하려면 백슬래시로 이스케이프합니다: `\$1.00`은 `$1.00`으로 렌더링됩니다. |
641| `model` | 아니요 | 평가에 사용할 모델. 기본값은 빠른 모델입니다. |641| `model` | 아니요 | 평가에 사용할 모델. 기본값은 빠른 모델입니다. |
642 642
788Hook 이벤트는 각 [hook 이벤트](#hook-events) 섹션에서 문서화된 이벤트 특정 필드 외에 이러한 필드를 JSON으로 받습니다. 명령 hook의 경우 이 JSON은 stdin을 통해 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다.788Hook 이벤트는 각 [hook 이벤트](#hook-events) 섹션에서 문서화된 이벤트 특정 필드 외에 이러한 필드를 JSON으로 받습니다. 명령 hook의 경우 이 JSON은 stdin을 통해 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다.
789 789
790| 필드 | 설명 |790| 필드 | 설명 |
791| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |791| :- | :- |
792| `session_id` | 현재 세션 식별자 |792| `session_id` | 현재 세션 식별자 |
793| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/docs/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 원격 분석과 연관시킬 수 있습니다. 첫 번째 사용자 입력까지 없습니다. Claude Code v2.1.196 이상 필요 |793| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/docs/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 원격 분석과 연관시킬 수 있습니다. 첫 번째 사용자 입력까지 없습니다. Claude Code v2.1.196 이상 필요 |
794| `transcript_path` | 대화 JSON 경로입니다. 트랜스크립트 파일은 비동기적으로 기록되며 메모리 내 대화보다 뒤떨어질 수 있으므로 hook이 발생할 때 현재 턴의 가장 최근 메시지를 아직 포함하지 않을 수 있습니다. 현재 턴의 최종 어시스턴트 텍스트가 필요한 hook은 트랜스크립트를 읽는 대신 [Stop](#stop) 및 [SubagentStop](#subagentstop)에서 `last_assistant_message`를 사용해야 합니다 |794| `transcript_path` | 대화 JSON 경로입니다. 트랜스크립트 파일은 비동기적으로 기록되며 메모리 내 대화보다 뒤떨어질 수 있으므로 hook이 발생할 때 현재 턴의 가장 최근 메시지를 아직 포함하지 않을 수 있습니다. 현재 턴의 최종 어시스턴트 텍스트가 필요한 hook은 트랜스크립트를 읽는 대신 [Stop](#stop) 및 [SubagentStop](#subagentstop)에서 `last_assistant_message`를 사용해야 합니다 |
801`--agent`로 실행하거나 subagent 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:801`--agent`로 실행하거나 subagent 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:
802 802
803| 필드 | 설명 |803| 필드 | 설명 |
804| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |804| :- | :- |
805| `agent_id` | subagent의 고유 식별자. hook이 subagent 호출 내부에서 발생할 때만 존재합니다. 이를 사용하여 subagent hook 호출을 메인 스레드 호출과 구별합니다. |805| `agent_id` | subagent의 고유 식별자. hook이 subagent 호출 내부에서 발생할 때만 존재합니다. 이를 사용하여 subagent hook 호출을 메인 스레드 호출과 구별합니다. |
806| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 subagent 내부에서 발생할 때 존재합니다. subagent의 경우 subagent의 유형이 세션의 `--agent` 값보다 우선합니다. [SubagentStart](#subagentstart)에서 사용자 정의 및 플러그인 subagent가 보고하는 값과 플러그인 범위 이름에 대해 matcher를 작성하는 방법을 참조하세요. |806| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 subagent 내부에서 발생할 때 존재합니다. subagent의 경우 subagent의 유형이 세션의 `--agent` 값보다 우선합니다. [SubagentStart](#subagentstart)에서 사용자 정의 및 플러그인 subagent가 보고하는 값과 플러그인 범위 이름에 대해 matcher를 작성하는 방법을 참조하세요. |
807 807
928종료 코드 2는 hook이 "멈춰, 이것을 하지 마"라고 신호하는 방식입니다. 효과는 이벤트에 따라 다릅니다. 일부 이벤트는 차단할 수 있는 작업을 나타내기 때문입니다 (아직 발생하지 않은 도구 호출처럼) 그리고 다른 이벤트는 이미 발생했거나 방지할 수 없는 것을 나타냅니다.928종료 코드 2는 hook이 "멈춰, 이것을 하지 마"라고 신호하는 방식입니다. 효과는 이벤트에 따라 다릅니다. 일부 이벤트는 차단할 수 있는 작업을 나타내기 때문입니다 (아직 발생하지 않은 도구 호출처럼) 그리고 다른 이벤트는 이미 발생했거나 방지할 수 없는 것을 나타냅니다.
929 929
930| Hook 이벤트 | 차단 가능? | 종료 코드 2에서 발생하는 것 |930| Hook 이벤트 | 차단 가능? | 종료 코드 2에서 발생하는 것 |
931| :-------------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |931| :- | :- | :- |
932| `PreToolUse` | 예 | 도구 호출을 차단합니다 |932| `PreToolUse` | 예 | 도구 호출을 차단합니다 |
933| `PermissionRequest` | 아니오 | 종료 코드 2는 이 이벤트에 대해 수행되지 않으며 권한 흐름은 변경되지 않고 진행됩니다. 대신 [`decision` 객체](#permissionrequest-decision-control)를 통해 거부합니다 |933| `PermissionRequest` | 아니오 | 종료 코드 2는 이 이벤트에 대해 수행되지 않으며 권한 흐름은 변경되지 않고 진행됩니다. 대신 [`decision` 객체](#permissionrequest-decision-control)를 통해 거부합니다 |
934| `UserPromptSubmit` | 예 | 프롬프트 처리를 차단하고 프롬프트를 지웁니다 |934| `UserPromptSubmit` | 예 | 프롬프트 처리를 차단하고 프롬프트를 지웁니다 |
1005* \*\*`hookSpecificOutput`\*\*은 더 풍부한 제어가 필요한 이벤트를 위한 중첩 객체입니다. 이벤트 이름으로 설정된 `hookEventName` 필드가 필요합니다.1005* \*\*`hookSpecificOutput`\*\*은 더 풍부한 제어가 필요한 이벤트를 위한 중첩 객체입니다. 이벤트 이름으로 설정된 `hookEventName` 필드가 필요합니다.
1006 1006
1007| 필드 | 기본값 | 설명 |1007| 필드 | 기본값 | 설명 |
1008| :----------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1008| :- | :- | :- |
1009| `continue` | `true` | `false`인 경우 hook이 실행된 후 Claude가 완전히 중지됩니다. 모든 이벤트 특정 결정 필드보다 우선합니다 |1009| `continue` | `true` | `false`인 경우 hook이 실행된 후 Claude가 완전히 중지됩니다. 모든 이벤트 특정 결정 필드보다 우선합니다 |
1010| `stopReason` | 없음 | `continue`가 `false`일 때 사용자에게 표시되는 메시지. 대화에 남아 있으므로 대화가 계속되면 Claude가 이를 봅니다 |1010| `stopReason` | 없음 | `continue`가 `false`일 때 사용자에게 표시되는 메시지. 대화에 남아 있으므로 대화가 계속되면 Claude가 이를 봅니다 |
1011| `suppressOutput` | `false` | 효과 없음: Claude Code는 필드를 허용하지만 작동하지 않습니다. 성공한 hook의 stdout은 트랜스크립트에 표시되지 않으며 디버그 로그에 기록됩니다 |1011| `suppressOutput` | `false` | 효과 없음: Claude Code는 필드를 허용하지만 작동하지 않습니다. 성공한 hook의 stdout은 트랜스크립트에 표시되지 않으며 디버그 로그에 기록됩니다 |
1103모든 이벤트가 JSON을 통해 동작을 차단하거나 제어하는 것을 지원하는 것은 아닙니다. 그렇게 하는 이벤트는 각각 다른 필드 집합을 사용하여 해당 결정을 표현합니다. hook을 작성하기 전에 이 표를 빠른 참조로 사용하세요:1103모든 이벤트가 JSON을 통해 동작을 차단하거나 제어하는 것을 지원하는 것은 아닙니다. 그렇게 하는 이벤트는 각각 다른 필드 집합을 사용하여 해당 결정을 표현합니다. hook을 작성하기 전에 이 표를 빠른 참조로 사용하세요:
1104 1104
1105| 이벤트 | 결정 패턴 | 주요 필드 |1105| 이벤트 | 결정 패턴 | 주요 필드 |
1106| :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1106| :- | :- | :- |
1107| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | 최상위 `decision` | `decision: "block"`, `reason`. Stop 및 SubagentStop은 또한 [오류가 아닌 피드백을 위해 대화를 계속하는](#stop-decision-control) `hookSpecificOutput.additionalContext`를 허용합니다 |1107| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | 최상위 `decision` | `decision: "block"`, `reason`. Stop 및 SubagentStop은 또한 [오류가 아닌 피드백을 위해 대화를 계속하는](#stop-decision-control) `hookSpecificOutput.additionalContext`를 허용합니다 |
1108| TeammateIdle, TaskCompleted | 종료 코드 또는 `continue: false` | 종료 코드 2는 stderr 피드백으로 작업을 차단합니다. JSON `{"continue": false, "stopReason": "..."}` 또한 팀원을 완전히 중지하여 `Stop` hook 동작과 일치합니다. [TaskCompleted는 `TaskUpdate` 도구가 이벤트를 트리거했을 때 이를 무시합니다](#taskcompleted-decision-control) |1108| TeammateIdle, TaskCompleted | 종료 코드 또는 `continue: false` | 종료 코드 2는 stderr 피드백으로 작업을 차단합니다. JSON `{"continue": false, "stopReason": "..."}` 또한 팀원을 완전히 중지하여 `Stop` hook 동작과 일치합니다. [TaskCompleted는 `TaskUpdate` 도구가 이벤트를 트리거했을 때 이를 무시합니다](#taskcompleted-decision-control) |
1109| TaskCreated | 종료 코드 또는 최상위 `decision` | 종료 코드 2 또는 `decision: "block"`은 [작업을 취소](#taskcreated-decision-control)하고 메시지를 Claude에 반환합니다. `continue: false`는 무시됩니다 |1109| TaskCreated | 종료 코드 또는 최상위 `decision` | 종료 코드 2 또는 `decision: "block"`은 [작업을 취소](#taskcreated-decision-control)하고 메시지를 Claude에 반환합니다. `continue: false`는 무시됩니다 |
1194matcher 값은 세션이 시작된 방식에 해당합니다:1194matcher 값은 세션이 시작된 방식에 해당합니다:
1195 1195
1196| Matcher | 언제 발생하는지 |1196| Matcher | 언제 발생하는지 |
1197| :-------- | :--------------------------------------------------------------------------------------------- |1197| :- | :- |
1198| `startup` | 새 세션 |1198| `startup` | 새 세션 |
1199| `resume` | `--resume`, `--continue` 또는 `/resume` |1199| `resume` | `--resume`, `--continue` 또는 `/resume` |
1200| `clear` | `/clear` |1200| `clear` | `/clear` |
1218[공통 입력 필드](#common-input-fields) 외에도 SessionStart hook은 `source` 및 선택적으로 `model`, `agent_type`, `session_title`을 받습니다:1218[공통 입력 필드](#common-input-fields) 외에도 SessionStart hook은 `source` 및 선택적으로 `model`, `agent_type`, `session_title`을 받습니다:
1219 1219
1220| 필드 | 설명 |1220| 필드 | 설명 |
1221| :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |1221| :- | :- |
1222| `source` | 세션이 시작된 방식: 새 세션의 경우 `"startup"`, 재개된 세션의 경우 `"resume"`, `/clear` 후 `"clear"`, 압축 후 `"compact"`, 또는 기존 세션에서 포크된 새 세션의 경우 `"fork"` |1222| `source` | 세션이 시작된 방식: 새 세션의 경우 `"startup"`, 재개된 세션의 경우 `"resume"`, `/clear` 후 `"clear"`, 압축 후 `"compact"`, 또는 기존 세션에서 포크된 새 세션의 경우 `"fork"` |
1223| `model` | 활성 모델 식별자. 예를 들어 `/clear` 후 또는 대화 복구를 통해 세션이 복원될 때 생략될 수 있으므로 필드를 읽기 전에 확인하세요 |1223| `model` | 활성 모델 식별자. 예를 들어 `/clear` 후 또는 대화 복구를 통해 세션이 복원될 때 생략될 수 있으므로 필드를 읽기 전에 확인하세요 |
1224| `agent_type` | `claude --agent <name>`으로 Claude Code를 시작할 때 존재하는 에이전트 이름 |1224| `agent_type` | `claude --agent <name>`으로 Claude Code를 시작할 때 존재하는 에이전트 이름 |
1227`source`가 `"resume"` 또는 `"fork"`이고 트랜스크립트에 Claude의 응답이 최소 하나 포함되어 있을 때 SessionStart hook은 아래의 네 필드도 받습니다. Hook은 이를 사용하여 첫 번째 요청 전에 오래된 대화를 재개하는 비용을 보고할 수 있습니다 (예: [`systemMessage`](#json-output)에서). 이 필드는 Claude Code v2.1.251 이상이 필요합니다.1227`source`가 `"resume"` 또는 `"fork"`이고 트랜스크립트에 Claude의 응답이 최소 하나 포함되어 있을 때 SessionStart hook은 아래의 네 필드도 받습니다. Hook은 이를 사용하여 첫 번째 요청 전에 오래된 대화를 재개하는 비용을 보고할 수 있습니다 (예: [`systemMessage`](#json-output)에서). 이 필드는 Claude Code v2.1.251 이상이 필요합니다.
1228 1228
1229| 필드 | 설명 |1229| 필드 | 설명 |
1230| :---------------------------- | :------------------------------------------------------------------------------------------------------ |1230| :- | :- |
1231| `seconds_since_last_response` | 재개된 트랜스크립트의 마지막 응답 이후의 벽시계 초 |1231| `seconds_since_last_response` | 재개된 트랜스크립트의 마지막 응답 이후의 벽시계 초 |
1232| `context_tokens` | 재개된 세션의 첫 번째 요청이 프롬프트로 다시 전송하는 토큰 |1232| `context_tokens` | 재개된 세션의 첫 번째 요청이 프롬프트로 다시 전송하는 토큰 |
1233| `prompt_cache_likely_expired` | 마지막 응답이 세션의 [prompt cache 수명](/docs/ko/prompt-caching#cache-lifetime)보다 오래되었거나 나중의 압축이 캐시된 대화를 대체했을 때 `true` |1233| `prompt_cache_likely_expired` | 마지막 응답이 세션의 [prompt cache 수명](/docs/ko/prompt-caching#cache-lifetime)보다 오래되었거나 나중의 압축이 캐시된 대화를 대체했을 때 `true` |
1257Claude Code는 [일반 텍스트로 처리하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 이러한 이벤트 특정 필드를 반환할 수 있습니다:1257Claude Code는 [일반 텍스트로 처리하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 이러한 이벤트 특정 필드를 반환할 수 있습니다:
1258 1258
1259| 필드 | 설명 |1259| 필드 | 설명 |
1260| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1260| :- | :- |
1261| `additionalContext` | 대화 시작 부분, 첫 번째 프롬프트 전에 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 텍스트가 전달되는 방식과 포함할 내용을 확인하세요 |1261| `additionalContext` | 대화 시작 부분, 첫 번째 프롬프트 전에 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 텍스트가 전달되는 방식과 포함할 내용을 확인하세요 |
1262| `initialUserMessage` | 세션의 첫 번째 사용자 메시지로 사용되는 문자열. [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그와 함께 적용되며, 프롬프트가 제공되지 않으면 첫 번째 턴이 됩니다. 프롬프트가 제공되면 다음 턴으로 따릅니다. `additionalContext`와 달리 기존 턴에 첨부되는 이것은 턴을 생성합니다 |1262| `initialUserMessage` | 세션의 첫 번째 사용자 메시지로 사용되는 문자열. [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그와 함께 적용되며, 프롬프트가 제공되지 않으면 첫 번째 턴이 됩니다. 프롬프트가 제공되면 다음 턴으로 따릅니다. `additionalContext`와 달리 기존 턴에 첨부되는 이것은 턴을 생성합니다 |
1263| `sessionTitle` | 세션 제목을 설정합니다. `/rename`과 동일한 효과입니다. 시작 폴더, git 분기 또는 worktree 이름에서 세션을 자동으로 이름 지정하는 데 사용합니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용됩니다; `"clear"` 및 `"compact"`에서는 무시됩니다 |1263| `sessionTitle` | 세션 제목을 설정합니다. `/rename`과 동일한 효과입니다. 시작 폴더, git 분기 또는 worktree 이름에서 세션을 자동으로 이름 지정하는 데 사용합니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용됩니다; `"clear"` 및 `"compact"`에서는 무시됩니다 |
1341matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:1341matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:
1342 1342
1343| Matcher | 언제 발생하는지 |1343| Matcher | 언제 발생하는지 |
1344| :------------ | :----------------------------------------- |1344| :- | :- |
1345| `init` | `claude --init-only` 또는 `claude -p --init` |1345| `init` | `claude --init-only` 또는 `claude -p --init` |
1346| `maintenance` | `claude -p --maintenance` |1346| `maintenance` | `claude -p --maintenance` |
1347 1347
1394[공통 입력 필드](#common-input-fields) 외에도 InstructionsLoaded hook은 이러한 필드를 받습니다:1394[공통 입력 필드](#common-input-fields) 외에도 InstructionsLoaded hook은 이러한 필드를 받습니다:
1395 1395
1396| 필드 | 설명 |1396| 필드 | 설명 |
1397| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- |1397| :- | :- |
1398| `file_path` | 로드된 명령 파일의 절대 경로 |1398| `file_path` | 로드된 명령 파일의 절대 경로 |
1399| `memory_type` | 파일의 범위: `"User"`, `"Project"`, `"Local"` 또는 `"Managed"` |1399| `memory_type` | 파일의 범위: `"User"`, `"Project"`, `"Local"` 또는 `"Managed"` |
1400| `load_reason` | 파일이 로드된 이유: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` 또는 `"compact"`. `"compact"` 값은 압축 이벤트 후 명령 파일이 다시 로드될 때 발생합니다 |1400| `load_reason` | 파일이 로드된 이유: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` 또는 `"compact"`. `"compact"` 값은 압축 이벤트 후 명령 파일이 다시 로드될 때 발생합니다 |
1465프롬프트를 차단하려면 `decision`을 `"block"`으로 설정한 JSON 객체를 반환합니다:1465프롬프트를 차단하려면 `decision`을 `"block"`으로 설정한 JSON 객체를 반환합니다:
1466 1466
1467| 필드 | 설명 |1467| 필드 | 설명 |
1468| :----------------------- | :---------------------------------------------------------------------------------------- |1468| :- | :- |
1469| `decision` | `"block"`은 프롬프트가 처리되는 것을 방지하고 컨텍스트에서 지웁니다. 생략하여 프롬프트를 진행하도록 허용 |1469| `decision` | `"block"`은 프롬프트가 처리되는 것을 방지하고 컨텍스트에서 지웁니다. 생략하여 프롬프트를 진행하도록 허용 |
1470| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다. 컨텍스트에 추가되지 않음 |1470| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다. 컨텍스트에 추가되지 않음 |
1471| `additionalContext` | Claude의 컨텍스트에 제출된 프롬프트와 함께 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |1471| `additionalContext` | Claude의 컨텍스트에 제출된 프롬프트와 함께 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
1524`UserPromptExpansion` hook은 확장을 차단하거나 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.1524`UserPromptExpansion` hook은 확장을 차단하거나 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.
1525 1525
1526| 필드 | 설명 |1526| 필드 | 설명 |
1527| :------------------ | :---------------------------------------------------------------------------------------- |1527| :- | :- |
1528| `decision` | `"block"`은 slash 명령이 확장되는 것을 방지합니다. 생략하여 진행하도록 허용 |1528| `decision` | `"block"`은 slash 명령이 확장되는 것을 방지합니다. 생략하여 진행하도록 허용 |
1529| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다 |1529| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다 |
1530| `additionalContext` | 확장된 프롬프트와 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |1530| `additionalContext` | 확장된 프롬프트와 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
1569[공통 입력 필드](#common-input-fields) 외에도 MessageDisplay hook은 턴과 메시지의 식별자, 이 호출이 메시지 내에서의 위치, `delta`의 새 텍스트를 받습니다. 배치 경계는 텍스트가 스트리밍되는 방식에 따라 다르므로 줄이 특정 방식으로 그룹화될 것으로 예상하기보다는 `index` 및 `final`을 사용하여 메시지를 통한 진행 상황을 추적합니다.1569[공통 입력 필드](#common-input-fields) 외에도 MessageDisplay hook은 턴과 메시지의 식별자, 이 호출이 메시지 내에서의 위치, `delta`의 새 텍스트를 받습니다. 배치 경계는 텍스트가 스트리밍되는 방식에 따라 다르므로 줄이 특정 방식으로 그룹화될 것으로 예상하기보다는 `index` 및 `final`을 사용하여 메시지를 통한 진행 상황을 추적합니다.
1570 1570
1571| 필드 | 설명 |1571| 필드 | 설명 |
1572| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1572| :- | :- |
1573| `turn_id` | 현재 턴의 UUID |1573| `turn_id` | 현재 턴의 UUID |
1574| `message_id` | 표시되는 어시스턴트 메시지의 UUID. 메시지의 모든 배치에서 안정적입니다. 이는 API `msg_…` id가 아니므로 트랜스크립트 메시지 id와 상관관계를 지을 수 없습니다 |1574| `message_id` | 표시되는 어시스턴트 메시지의 UUID. 메시지의 모든 배치에서 안정적입니다. 이는 API `msg_…` id가 아니므로 트랜스크립트 메시지 id와 상관관계를 지을 수 없습니다 |
1575| `index` | 메시지 내 이 배치의 0 기반 인덱스 |1575| `index` | 메시지 내 이 배치의 0 기반 인덱스 |
1597모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 MessageDisplay hook은 `displayContent`를 반환하여 화면의 delta를 바꿀 수 있습니다:1597모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 MessageDisplay hook은 `displayContent`를 반환하여 화면의 delta를 바꿀 수 있습니다:
1598 1598
1599| 필드 | 설명 |1599| 필드 | 설명 |
1600| :--------------- | :----------------------------- |1600| :- | :- |
1601| `displayContent` | delta 대신 표시되는 텍스트. 생략하여 원본을 표시 |1601| `displayContent` | delta 대신 표시되는 텍스트. 생략하여 원본을 표시 |
1602 1602
1603MessageDisplay hook은 결정 제어가 없습니다. 메시지를 차단하거나 트랜스크립트에 저장되거나 Claude에 전송되는 것을 변경할 수 없습니다. Claude Code는 이들의 JSON 출력에서 `displayContent`를 작동하고 `systemMessage` 및 `continue`를 삭제합니다.1603MessageDisplay hook은 결정 제어가 없습니다. 메시지를 차단하거나 트랜스크립트에 저장되거나 Claude에 전송되는 것을 변경할 수 없습니다. Claude Code는 이들의 JSON 출력에서 `displayContent`를 작동하고 `systemMessage` 및 `continue`를 삭제합니다.
1738셸 명령을 실행합니다.1738셸 명령을 실행합니다.
1739 1739
1740| 필드 | 유형 | 예제 | 설명 |1740| 필드 | 유형 | 예제 | 설명 |
1741| :------------------ | :-- | :----------------- | :--------------------------------------------------------------------------------------- |1741| :- | :- | :- | :- |
1742| `command` | 문자열 | `"npm test"` | 실행할 셸 명령 |1742| `command` | 문자열 | `"npm test"` | 실행할 셸 명령 |
1743| `description` | 문자열 | `"Run test suite"` | 명령이 수행하는 작업의 선택적 설명 |1743| `description` | 문자열 | `"Run test suite"` | 명령이 수행하는 작업의 선택적 설명 |
1744| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초). [최대](/docs/ko/tools-reference#bash-tool-behavior) 이상의 값은 거부되지 않고 최대값으로 감소됩니다 |1744| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초). [최대](/docs/ko/tools-reference#bash-tool-behavior) 이상의 값은 거부되지 않고 최대값으로 감소됩니다 |
1755`changedFiles` 및 `files`는 명령이 변경한 내용을 나열합니다; 나머지 필드는 해당 목록이 얼마나 완전하고 신뢰할 수 있는지를 말합니다.1755`changedFiles` 및 `files`는 명령이 변경한 내용을 나열합니다; 나머지 필드는 해당 목록이 얼마나 완전하고 신뢰할 수 있는지를 말합니다.
1756 1756
1757| 필드 | 유형 | 예제 | 설명 |1757| 필드 | 유형 | 예제 | 설명 |
1758| :------------- | :- | :------------------------------------------------------ | :------------------------------------------------------------------------------------------ |1758| :- | :- | :- | :- |
1759| `changedFiles` | 배열 | `["/path/to/src/app.ts"]` | 명령이 변경한 파일의 절대 경로, 최대 200개. `files`가 diff를 보유하거나 `moreFiles`가 0 이상일 때마다 존재 |1759| `changedFiles` | 배열 | `["/path/to/src/app.ts"]` | 명령이 변경한 파일의 절대 경로, 최대 200개. `files`가 diff를 보유하거나 `moreFiles`가 0 이상일 때마다 존재 |
1760| `files` | 배열 | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 최대 5개의 변경된 파일의 diff, 표시용. 명령이 추가하거나 제거한 파일의 경우 `created` 또는 `deleted`는 `true` |1760| `files` | 배열 | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 최대 5개의 변경된 파일의 diff, 표시용. 명령이 추가하거나 제거한 파일의 경우 `created` 또는 `deleted`는 `true` |
1761| `moreFiles` | 숫자 | `2` | `files`에 diff가 없는 변경된 파일의 개수 |1761| `moreFiles` | 숫자 | `2` | `files`에 diff가 없는 변경된 파일의 개수 |
1774필드는 Bash 도구와 일치하며 `command` 문자열에 명령이 있습니다:1774필드는 Bash 도구와 일치하며 `command` 문자열에 명령이 있습니다:
1775 1775
1776| 필드 | 유형 | 예제 | 설명 |1776| 필드 | 유형 | 예제 | 설명 |
1777| :------------------ | :-- | :------------------------- | :------------------ |1777| :- | :- | :- | :- |
1778| `command` | 문자열 | `"Get-ChildItem -Recurse"` | 실행할 PowerShell 명령 |1778| `command` | 문자열 | `"Get-ChildItem -Recurse"` | 실행할 PowerShell 명령 |
1779| `description` | 문자열 | `"List files recursively"` | 명령이 수행하는 작업의 선택적 설명 |1779| `description` | 문자열 | `"List files recursively"` | 명령이 수행하는 작업의 선택적 설명 |
1780| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초) |1780| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초) |
1793파일을 생성하거나 덮어씁니다.1793파일을 생성하거나 덮어씁니다.
1794 1794
1795| 필드 | 유형 | 예제 | 설명 |1795| 필드 | 유형 | 예제 | 설명 |
1796| :---------- | :-- | :-------------------- | :---------- |1796| :- | :- | :- | :- |
1797| `file_path` | 문자열 | `"/path/to/file.txt"` | 쓸 파일의 절대 경로 |1797| `file_path` | 문자열 | `"/path/to/file.txt"` | 쓸 파일의 절대 경로 |
1798| `content` | 문자열 | `"file content"` | 파일에 쓸 내용 |1798| `content` | 문자열 | `"file content"` | 파일에 쓸 내용 |
1799 1799
1804기존 파일의 문자열을 바꿉니다.1804기존 파일의 문자열을 바꿉니다.
1805 1805
1806| 필드 | 유형 | 예제 | 설명 |1806| 필드 | 유형 | 예제 | 설명 |
1807| :------------ | :-- | :-------------------- | :------------ |1807| :- | :- | :- | :- |
1808| `file_path` | 문자열 | `"/path/to/file.txt"` | 편집할 파일의 절대 경로 |1808| `file_path` | 문자열 | `"/path/to/file.txt"` | 편집할 파일의 절대 경로 |
1809| `old_string` | 문자열 | `"original text"` | 찾아 바꿀 텍스트 |1809| `old_string` | 문자열 | `"original text"` | 찾아 바꿀 텍스트 |
1810| `new_string` | 문자열 | `"replacement text"` | 대체 텍스트 |1810| `new_string` | 문자열 | `"replacement text"` | 대체 텍스트 |
1817파일 내용을 읽습니다.1817파일 내용을 읽습니다.
1818 1818
1819| 필드 | 유형 | 예제 | 설명 |1819| 필드 | 유형 | 예제 | 설명 |
1820| :---------- | :-- | :-------------------- | :--------------- |1820| :- | :- | :- | :- |
1821| `file_path` | 문자열 | `"/path/to/file.txt"` | 읽을 파일의 절대 경로 |1821| `file_path` | 문자열 | `"/path/to/file.txt"` | 읽을 파일의 절대 경로 |
1822| `offset` | 숫자 | `10` | 읽기를 시작할 선택적 줄 번호 |1822| `offset` | 숫자 | `10` | 읽기를 시작할 선택적 줄 번호 |
1823| `limit` | 숫자 | `50` | 읽을 선택적 줄 수 |1823| `limit` | 숫자 | `50` | 읽을 선택적 줄 수 |
1829glob 패턴과 일치하는 파일을 찾습니다.1829glob 패턴과 일치하는 파일을 찾습니다.
1830 1830
1831| 필드 | 유형 | 예제 | 설명 |1831| 필드 | 유형 | 예제 | 설명 |
1832| :-------- | :-- | :--------------- | :---------------------------- |1832| :- | :- | :- | :- |
1833| `pattern` | 문자열 | `"**/*.ts"` | 파일과 일치시킬 glob 패턴 |1833| `pattern` | 문자열 | `"**/*.ts"` | 파일과 일치시킬 glob 패턴 |
1834| `path` | 문자열 | `"/path/to/dir"` | 검색할 선택적 디렉토리. 기본값은 현재 작업 디렉토리 |1834| `path` | 문자열 | `"/path/to/dir"` | 검색할 선택적 디렉토리. 기본값은 현재 작업 디렉토리 |
1835 1835
1840정규식으로 파일 내용을 검색합니다.1840정규식으로 파일 내용을 검색합니다.
1841 1841
1842| 필드 | 유형 | 예제 | 설명 |1842| 필드 | 유형 | 예제 | 설명 |
1843| :------------ | :-- | :--------------- | :---------------------------------------------------------------------------- |1843| :- | :- | :- | :- |
1844| `pattern` | 문자열 | `"TODO.*fix"` | 검색할 정규식 패턴 |1844| `pattern` | 문자열 | `"TODO.*fix"` | 검색할 정규식 패턴 |
1845| `path` | 문자열 | `"/path/to/dir"` | 검색할 선택적 파일 또는 디렉토리 |1845| `path` | 문자열 | `"/path/to/dir"` | 검색할 선택적 파일 또는 디렉토리 |
1846| `glob` | 문자열 | `"*.ts"` | 파일을 필터링할 선택적 glob 패턴 |1846| `glob` | 문자열 | `"*.ts"` | 파일을 필터링할 선택적 glob 패턴 |
1855웹 콘텐츠를 가져오고 처리합니다.1855웹 콘텐츠를 가져오고 처리합니다.
1856 1856
1857| 필드 | 유형 | 예제 | 설명 |1857| 필드 | 유형 | 예제 | 설명 |
1858| :------- | :-- | :---------------------------- | :----------------- |1858| :- | :- | :- | :- |
1859| `url` | 문자열 | `"https://example.com/api"` | 콘텐츠를 가져올 URL |1859| `url` | 문자열 | `"https://example.com/api"` | 콘텐츠를 가져올 URL |
1860| `prompt` | 문자열 | `"Extract the API endpoints"` | 가져온 콘텐츠에서 실행할 프롬프트 |1860| `prompt` | 문자열 | `"Extract the API endpoints"` | 가져온 콘텐츠에서 실행할 프롬프트 |
1861 1861
1866웹을 검색합니다.1866웹을 검색합니다.
1867 1867
1868| 필드 | 유형 | 예제 | 설명 |1868| 필드 | 유형 | 예제 | 설명 |
1869| :---------------- | :-- | :----------------------------- | :------------------- |1869| :- | :- | :- | :- |
1870| `query` | 문자열 | `"react hooks best practices"` | 검색 쿼리 |1870| `query` | 문자열 | `"react hooks best practices"` | 검색 쿼리 |
1871| `allowed_domains` | 배열 | `["docs.example.com"]` | 선택적: 이러한 도메인의 결과만 포함 |1871| `allowed_domains` | 배열 | `["docs.example.com"]` | 선택적: 이러한 도메인의 결과만 포함 |
1872| `blocked_domains` | 배열 | `["spam.example.com"]` | 선택적: 이러한 도메인의 결과 제외 |1872| `blocked_domains` | 배열 | `["spam.example.com"]` | 선택적: 이러한 도메인의 결과 제외 |
1878[subagent](/docs/ko/sub-agents)를 생성합니다.1878[subagent](/docs/ko/sub-agents)를 생성합니다.
1879 1879
1880| 필드 | 유형 | 예제 | 설명 |1880| 필드 | 유형 | 예제 | 설명 |
1881| :-------------- | :-- | :------------------------- | :------------------ |1881| :- | :- | :- | :- |
1882| `prompt` | 문자열 | `"Find all API endpoints"` | 에이전트가 수행할 작업 |1882| `prompt` | 문자열 | `"Find all API endpoints"` | 에이전트가 수행할 작업 |
1883| `description` | 문자열 | `"Find API endpoints"` | 작업의 짧은 설명 |1883| `description` | 문자열 | `"Find API endpoints"` | 작업의 짧은 설명 |
1884| `subagent_type` | 문자열 | `"Explore"` | 사용할 특화된 에이전트의 유형 |1884| `subagent_type` | 문자열 | `"Explore"` | 사용할 특화된 에이전트의 유형 |
1887foreground Agent 호출이 완료되면 [PostToolUse hook](#posttooluse)은 subagent의 결과와 실행 원격 측정을 `tool_response`에서 받습니다. 이 필드를 읽어 실행을 검사합니다; subagent 전체의 토큰 및 비용 롤업의 경우 [토큰 및 비용 카운터](/docs/ko/monitoring-usage#token-counter)를 `query_source` `"subagent"`로 필터링하여 사용합니다 (`totalTokens` 및 `usage`는 최종 요청만 다룹니다):1887foreground Agent 호출이 완료되면 [PostToolUse hook](#posttooluse)은 subagent의 결과와 실행 원격 측정을 `tool_response`에서 받습니다. 이 필드를 읽어 실행을 검사합니다; subagent 전체의 토큰 및 비용 롤업의 경우 [토큰 및 비용 카운터](/docs/ko/monitoring-usage#token-counter)를 `query_source` `"subagent"`로 필터링하여 사용합니다 (`totalTokens` 및 `usage`는 최종 요청만 다룹니다):
1888 1888
1889| 필드 | 유형 | 예제 | 설명 |1889| 필드 | 유형 | 예제 | 설명 |
1890| :------------------ | :-- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1890| :- | :- | :- | :- |
1891| `status` | 문자열 | `"completed"` | foreground subagent의 경우 `"completed"`, 백그라운드 subagent의 경우 `"async_launched"`. v2.1.198부터 subagent는 기본적으로 백그라운드에서 실행되므로 생략된 `run_in_background`도 `"async_launched"`를 생성합니다 |1891| `status` | 문자열 | `"completed"` | foreground subagent의 경우 `"completed"`, 백그라운드 subagent의 경우 `"async_launched"`. v2.1.198부터 subagent는 기본적으로 백그라운드에서 실행되므로 생략된 `run_in_background`도 `"async_launched"`를 생성합니다 |
1892| `agentId` | 문자열 | `"a4d2c8f1e0b3a297"` | subagent 실행의 식별자 |1892| `agentId` | 문자열 | `"a4d2c8f1e0b3a297"` | subagent 실행의 식별자 |
1893| `content` | 배열 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent의 최종 텍스트 블록, 또는 [`SubagentHandback`](/docs/ko/tools-reference)을 통해 보고서가 전달되는 subagent의 경우 그 손 전달에 대한 짧은 메모 |1893| `content` | 배열 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent의 최종 텍스트 블록, 또는 [`SubagentHandback`](/docs/ko/tools-reference)을 통해 보고서가 전달되는 subagent의 경우 그 손 전달에 대한 짧은 메모 |
1913사용자에게 1\~4개의 객관식 질문을 합니다.1913사용자에게 1\~4개의 객관식 질문을 합니다.
1914 1914
1915| 필드 | 유형 | 예제 | 설명 |1915| 필드 | 유형 | 예제 | 설명 |
1916| :---------- | :- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |1916| :- | :- | :- | :- |
1917| `questions` | 배열 | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 제시할 질문, 각각 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그 |1917| `questions` | 배열 | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 제시할 질문, 각각 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그 |
1918| `answers` | 객체 | `{"Which framework?": "React"}` | 선택적. 질문 텍스트를 선택한 옵션 레이블로 매핑합니다. 다중 선택 답변은 쉼표로 레이블을 결합합니다. Claude는 이 필드를 설정하지 않습니다; `updatedInput`을 통해 프로그래밍 방식으로 답변을 제공하세요 |1918| `answers` | 객체 | `{"Which framework?": "React"}` | 선택적. 질문 텍스트를 선택한 옵션 레이블로 매핑합니다. 다중 선택 답변은 쉼표로 레이블을 결합합니다. Claude는 이 필드를 설정하지 않습니다; `updatedInput`을 통해 프로그래밍 방식으로 답변을 제공하세요 |
1919 1919
1924Claude가 [plan 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 파일에 디스크에 작성하므로 모델의 리터럴 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 hook에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.1924Claude가 [plan 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 파일에 디스크에 작성하므로 모델의 리터럴 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 hook에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.
1925 1925
1926| 필드 | 유형 | 예제 | 설명 |1926| 필드 | 유형 | 예제 | 설명 |
1927| :--------------- | :-- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------ |1927| :- | :- | :- | :- |
1928| `plan` | 문자열 | `"## Refactor auth\n1. Extract..."` | Markdown의 계획 내용. 디스크의 계획 파일에서 주입됨 |1928| `plan` | 문자열 | `"## Refactor auth\n1. Extract..."` | Markdown의 계획 내용. 디스크의 계획 파일에서 주입됨 |
1929| `planFilePath` | 문자열 | `"/Users/.../plans/refactor-auth.md"` | 계획 파일의 경로. 주입됨 |1929| `planFilePath` | 문자열 | `"/Users/.../plans/refactor-auth.md"` | 계획 파일의 경로. 주입됨 |
1930| `allowedPrompts` | 배열 | `[{"tool": "Bash", "prompt": "run tests"}]` | 더 이상 사용되지 않음. Claude Code는 필드를 수락하지만 무시합니다. v2.1.205 이전에는 Claude가 계획을 구현하기 위해 요청하는 prompt 기반 권한을 전달했습니다 |1930| `allowedPrompts` | 배열 | `[{"tool": "Bash", "prompt": "run tests"}]` | 더 이상 사용되지 않음. Claude Code는 필드를 수락하지만 무시합니다. v2.1.205 이전에는 Claude가 계획을 구현하기 위해 요청하는 prompt 기반 권한을 전달했습니다 |
1938`PreToolUse` hook은 도구 호출 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 hook과 달리 PreToolUse는 `hookSpecificOutput` 객체 내에 결정을 반환합니다. 이는 더 풍부한 제어를 제공합니다: 네 가지 결과 (허용, 거부, 요청 또는 연기) 및 실행 전에 도구 입력을 수정하는 기능.1938`PreToolUse` hook은 도구 호출 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 hook과 달리 PreToolUse는 `hookSpecificOutput` 객체 내에 결정을 반환합니다. 이는 더 풍부한 제어를 제공합니다: 네 가지 결과 (허용, 거부, 요청 또는 연기) 및 실행 전에 도구 입력을 수정하는 기능.
1939 1939
1940| 필드 | 설명 |1940| 필드 | 설명 |
1941| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1941| :- | :- |
1942| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다 ([어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves) 및 [`updatedInput`과 쌍을 이루어야 하는](#allow-with-updatedinput) `AskUserQuestion` 및 `ExitPlanMode` 제외). `"deny"`는 도구 호출을 방지합니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 나중에 재개하도록 연기합니다. [거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 hook이 반환하는 것과 관계없이 여전히 평가됩니다 |1942| `permissionDecision` | `"allow"`는 권한 프롬프트를 건너뜁니다 ([어떤 모드도 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves) 및 [`updatedInput`과 쌍을 이루어야 하는](#allow-with-updatedinput) `AskUserQuestion` 및 `ExitPlanMode` 제외). `"deny"`는 도구 호출을 방지합니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 나중에 재개하도록 연기합니다. [거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 hook이 반환하는 것과 관계없이 여전히 평가됩니다 |
1943| `permissionDecisionReason` | `"allow"` 및 `"ask"`의 경우 사용자에게 표시되지만 Claude에는 표시되지 않습니다. `"deny"`의 경우 Claude에 표시됩니다. `"defer"`의 경우 무시됩니다 |1943| `permissionDecisionReason` | `"allow"` 및 `"ask"`의 경우 사용자에게 표시되지만 Claude에는 표시되지 않습니다. `"deny"`의 경우 Claude에 표시됩니다. `"defer"`의 경우 무시됩니다 |
1944| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. Claude Code는 권한 규칙과 Bash 명령의 [자동 백그라운드 적격성](/docs/ko/tools-reference#background-commands)을 hook이 반환하는 입력에 대해 평가합니다 (Claude가 보낸 입력이 아님). `"allow"`와 결합하여 자동 승인하거나 `"ask"`와 결합하여 수정된 입력을 사용자에게 표시합니다. `"defer"`의 경우 무시됩니다 |1944| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. Claude Code는 권한 규칙과 Bash 명령의 [자동 백그라운드 적격성](/docs/ko/tools-reference#background-commands)을 hook이 반환하는 입력에 대해 평가합니다 (Claude가 보낸 입력이 아님). `"allow"`와 결합하여 자동 승인하거나 `"ask"`와 결합하여 수정된 입력을 사용자에게 표시합니다. `"defer"`의 경우 무시됩니다 |
2070`PermissionRequest` hook은 권한 요청을 허용하거나 거부할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드가 있는 `decision` 객체를 반환할 수 있습니다:2070`PermissionRequest` hook은 권한 요청을 허용하거나 거부할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드가 있는 `decision` 객체를 반환할 수 있습니다:
2071 2071
2072| 필드 | 설명 |2072| 필드 | 설명 |
2073| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |2073| :- | :- |
2074| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가되므로 hook이 `"allow"`를 반환해도 일치하는 거부 규칙을 재정의하지 않습니다 |2074| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가되므로 hook이 `"allow"`를 반환해도 일치하는 거부 규칙을 재정의하지 않습니다 |
2075| `updatedInput` | `"allow"`만 해당: 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. 수정된 입력은 거부 및 요청 규칙에 대해 다시 평가됩니다 |2075| `updatedInput` | `"allow"`만 해당: 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. 수정된 입력은 거부 및 요청 규칙에 대해 다시 평가됩니다 |
2076| `updatedPermissions` | `"allow"`만 해당: 적용할 [권한 업데이트 항목](#permission-update-entries) 배열 (예: 허용 규칙 추가 또는 세션 권한 모드 변경) |2076| `updatedPermissions` | `"allow"`만 해당: 적용할 [권한 업데이트 항목](#permission-update-entries) 배열 (예: 허용 규칙 추가 또는 세션 권한 모드 변경) |
2100`updatedPermissions` 출력 필드와 [`permission_suggestions` 입력 필드](#permissionrequest-input) 모두 동일한 항목 객체 배열을 사용합니다. 각 항목에는 다른 필드를 결정하는 `type`과 변경이 작성되는 위치를 제어하는 `destination`이 있습니다.2100`updatedPermissions` 출력 필드와 [`permission_suggestions` 입력 필드](#permissionrequest-input) 모두 동일한 항목 객체 배열을 사용합니다. 각 항목에는 다른 필드를 결정하는 `type`과 변경이 작성되는 위치를 제어하는 `destination`이 있습니다.
2101 2101
2102| `type` | 필드 | 효과 |2102| `type` | 필드 | 효과 |
2103| :------------------ | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |2103| :- | :- | :- |
2104| `addRules` | `rules`, `behavior`, `destination` | 권한 규칙을 추가합니다. `rules`는 `{toolName, ruleContent?}` 객체의 배열입니다. 전체 도구와 일치하려면 `ruleContent`를 생략합니다. `behavior`는 `"allow"`, `"deny"` 또는 `"ask"`입니다 |2104| `addRules` | `rules`, `behavior`, `destination` | 권한 규칙을 추가합니다. `rules`는 `{toolName, ruleContent?}` 객체의 배열입니다. 전체 도구와 일치하려면 `ruleContent`를 생략합니다. `behavior`는 `"allow"`, `"deny"` 또는 `"ask"`입니다 |
2105| `replaceRules` | `rules`, `behavior`, `destination` | 주어진 `behavior`의 모든 규칙을 `destination`에서 제공된 `rules`로 바꿉니다 |2105| `replaceRules` | `rules`, `behavior`, `destination` | 주어진 `behavior`의 모든 규칙을 `destination`에서 제공된 `rules`로 바꿉니다 |
2106| `removeRules` | `rules`, `behavior`, `destination` | 주어진 `behavior`의 일치하는 규칙을 제거합니다 |2106| `removeRules` | `rules`, `behavior`, `destination` | 주어진 `behavior`의 일치하는 규칙을 제거합니다 |
2117모든 항목의 `destination` 필드는 변경이 메모리에만 유지되는지 또는 설정 파일에 유지되는지를 결정합니다.2117모든 항목의 `destination` 필드는 변경이 메모리에만 유지되는지 또는 설정 파일에 유지되는지를 결정합니다.
2118 2118
2119| `destination` | 쓰기 대상 |2119| `destination` | 쓰기 대상 |
2120| :---------------- | :---------------------------- |2120| :- | :- |
2121| `session` | 메모리 전용, 세션이 끝나면 삭제됨 |2121| `session` | 메모리 전용, 세션이 끝나면 삭제됨 |
2122| `localSettings` | `.claude/settings.local.json` |2122| `localSettings` | `.claude/settings.local.json` |
2123| `projectSettings` | `.claude/settings.json` |2123| `projectSettings` | `.claude/settings.json` |
2166```2166```
2167 2167
2168| 필드 | 설명 |2168| 필드 | 설명 |
2169| :------------ | :-------------------------------------------------------- |2169| :- | :- |
2170| `duration_ms` | 선택적. 도구 실행 시간 (밀리초). 권한 프롬프트 및 PreToolUse hook에 소요된 시간 제외 |2170| `duration_ms` | 선택적. 도구 실행 시간 (밀리초). 권한 프롬프트 및 PreToolUse hook에 소요된 시간 제외 |
2171 2171
2172<h4 id="posttooluse-decision-control">2172<h4 id="posttooluse-decision-control">
2176`PostToolUse` hook은 도구 실행 후 Claude에 피드백을 제공할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2176`PostToolUse` hook은 도구 실행 후 Claude에 피드백을 제공할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:
2177 2177
2178| 필드 | 설명 |2178| 필드 | 설명 |
2179| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2179| :- | :- |
2180| `decision` | `"block"`은 `reason`을 도구 결과 옆에 추가합니다. Claude는 여전히 원본 출력을 봅니다; 이를 바꾸려면 `updatedToolOutput`을 사용합니다 |2180| `decision` | `"block"`은 `reason`을 도구 결과 옆에 추가합니다. Claude는 여전히 원본 출력을 봅니다; 이를 바꾸려면 `updatedToolOutput`을 사용합니다 |
2181| `reason` | `decision`이 `"block"`일 때 Claude에 표시되는 설명 |2181| `reason` | `decision`이 `"block"`일 때 Claude에 표시되는 설명 |
2182| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2182| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
2278```2278```
2279 2279
2280| 필드 | 설명 |2280| 필드 | 설명 |
2281| :------------- | :-------------------------------------------------------------------------------------------------- |2281| :- | :- |
2282| `error` | 무엇이 잘못되었는지 설명하는 문자열. 형식은 실패한 도구에 따라 다릅니다 |2282| `error` | 무엇이 잘못되었는지 설명하는 문자열. 형식은 실패한 도구에 따라 다릅니다 |
2283| `is_interrupt` | 선택적 부울. 실패가 도구가 보고한 오류가 아닌 중단으로 도달했을 때 true. 실행 중인 도구를 취소하면 이 hook이 발생하지 않습니다; 도구 결과는 중단 메시지를 전달합니다 |2283| `is_interrupt` | 선택적 부울. 실패가 도구가 보고한 오류가 아닌 중단으로 도달했을 때 true. 실행 중인 도구를 취소하면 이 hook이 발생하지 않습니다; 도구 결과는 중단 메시지를 전달합니다 |
2284| `duration_ms` | 선택적. 도구 실행 시간 (밀리초). 권한 프롬프트 및 PreToolUse hook에 소요된 시간 제외 |2284| `duration_ms` | 선택적. 도구 실행 시간 (밀리초). 권한 프롬프트 및 PreToolUse hook에 소요된 시간 제외 |
2296`PostToolUseFailure` hook은 도구 실패 후 Claude에 컨텍스트를 제공할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2296`PostToolUseFailure` hook은 도구 실패 후 Claude에 컨텍스트를 제공할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:
2297 2297
2298| 필드 | 설명 |2298| 필드 | 설명 |
2299| :------------------ | :---------------------------------------------------------------------------------- |2299| :- | :- |
2300| `additionalContext` | Claude의 컨텍스트에 오류와 함께 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2300| `additionalContext` | Claude의 컨텍스트에 오류와 함께 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
2301 2301
2302```json theme={null}2302```json theme={null}
2357`PostToolBatch` hook은 Claude에 대한 컨텍스트를 주입할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2357`PostToolBatch` hook은 Claude에 대한 컨텍스트를 주입할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:
2358 2358
2359| 필드 | 설명 |2359| 필드 | 설명 |
2360| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------- |2360| :- | :- |
2361| `additionalContext` | 다음 모델 호출 전에 한 번 주입되는 컨텍스트 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 전달 세부 정보, 포함할 내용, 재개된 세션이 과거 값을 처리하는 방식을 확인하세요 |2361| `additionalContext` | 다음 모델 호출 전에 한 번 주입되는 컨텍스트 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 전달 세부 정보, 포함할 내용, 재개된 세션이 과거 값을 처리하는 방식을 확인하세요 |
2362 2362
2363```json theme={null}2363```json theme={null}
2403```2403```
2404 2404
2405| 필드 | 설명 |2405| 필드 | 설명 |
2406| :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2406| :- | :- |
2407| `reason` | 거부 이유. 분류기 판정의 경우 대부분의 세션에서 `[Data Exfiltration]`과 같은 대괄호의 일치하는 규칙 이름을 지정합니다; [거부 검토](/docs/ko/auto-mode-config#review-denials)를 참조하여 다른 형식을 확인하세요. [판정 없는 거부](#permissiondenied-decision-control)의 경우 `Auto mode could not evaluate this action and is blocking it for safety`로 시작합니다. 분류기 모델을 사용할 수 없어서 거부하는 경우 고정 텍스트 `Classifier unavailable`입니다 |2407| `reason` | 거부 이유. 분류기 판정의 경우 대부분의 세션에서 `[Data Exfiltration]`과 같은 대괄호의 일치하는 규칙 이름을 지정합니다; [거부 검토](/docs/ko/auto-mode-config#review-denials)를 참조하여 다른 형식을 확인하세요. [판정 없는 거부](#permissiondenied-decision-control)의 경우 `Auto mode could not evaluate this action and is blocking it for safety`로 시작합니다. 분류기 모델을 사용할 수 없어서 거부하는 경우 고정 텍스트 `Classifier unavailable`입니다 |
2408 2408
2409<h4 id="permissiondenied-decision-control">2409<h4 id="permissiondenied-decision-control">
2434데스크톱 알림이 꺼져 있어도 이 hook 이벤트를 받습니다: `preferredNotifChannel` 설정 (예: `notifications_disabled`)은 알림 방식만 변경하고 hook이 실행되는지 여부는 변경하지 않습니다.2434데스크톱 알림이 꺼져 있어도 이 hook 이벤트를 받습니다: `preferredNotifChannel` 설정 (예: `notifications_disabled`)은 알림 방식만 변경하고 hook이 실행되는지 여부는 변경하지 않습니다.
2435 2435
2436| Matcher | 언제 발생하는지 |2436| Matcher | 언제 발생하는지 |
2437| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2437| :- | :- |
2438| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대한 권한이 필요하고 프롬프트가 약 6초 대기했습니다 |2438| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대한 권한이 필요하고 프롬프트가 약 6초 대기했습니다 |
2439| `idle_prompt` | Claude가 약 60초 전에 응답을 마쳤고 입력하지 않았습니다 |2439| `idle_prompt` | Claude가 약 60초 전에 응답을 마쳤고 입력하지 않았습니다 |
2440| `auth_success` | 인증 완료 |2440| `auth_success` | 인증 완료 |
2551SubagentStart hook은 subagent 생성을 차단할 수 없지만 subagent에 컨텍스트를 주입할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다:2551SubagentStart hook은 subagent 생성을 차단할 수 없지만 subagent에 컨텍스트를 주입할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다:
2552 2552
2553| 필드 | 설명 |2553| 필드 | 설명 |
2554| :------------------ | :----------------------------------------------------------------------------------------------------- |2554| :- | :- |
2555| `additionalContext` | subagent의 대화 시작 부분에 추가되는 문자열. 첫 번째 프롬프트 전에 추가됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2555| `additionalContext` | subagent의 대화 시작 부분에 추가되는 문자열. 첫 번째 프롬프트 전에 추가됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
2556 2556
2557```json theme={null}2557```json theme={null}
2629```2629```
2630 2630
2631| 필드 | 설명 |2631| 필드 | 설명 |
2632| :----------------- | :----------------------- |2632| :- | :- |
2633| `task_id` | 생성되는 작업의 식별자 |2633| `task_id` | 생성되는 작업의 식별자 |
2634| `task_subject` | 작업의 제목 |2634| `task_subject` | 작업의 제목 |
2635| `task_description` | 작업의 자세한 설명. 없을 수 있음 |2635| `task_description` | 작업의 자세한 설명. 없을 수 있음 |
2690```2690```
2691 2691
2692| 필드 | 설명 |2692| 필드 | 설명 |
2693| :----------------- | :----------------------- |2693| :- | :- |
2694| `task_id` | 완료되는 작업의 식별자 |2694| `task_id` | 완료되는 작업의 식별자 |
2695| `task_subject` | 작업의 제목 |2695| `task_subject` | 작업의 제목 |
2696| `task_description` | 작업의 자세한 설명. 없을 수 있음 |2696| `task_description` | 작업의 자세한 설명. 없을 수 있음 |
2745`background_tasks`의 각 항목은 하나의 진행 중인 작업을 설명하며 이러한 필드를 사용합니다:2745`background_tasks`의 각 항목은 하나의 진행 중인 작업을 설명하며 이러한 필드를 사용합니다:
2746 2746
2747| 필드 | 설명 |2747| 필드 | 설명 |
2748| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2748| :- | :- |
2749| `id` | 작업 식별자 |2749| `id` | 작업 식별자 |
2750| `type` | 친화적 작업 유형 레이블 (예: `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, `MCP task`). 각 레이블은 어느 Claude Code 기능이 작업을 생성했는지 식별합니다. 인식되지 않는 유형의 경우 원본 판별식으로 폴백 |2750| `type` | 친화적 작업 유형 레이블 (예: `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, `MCP task`). 각 레이블은 어느 Claude Code 기능이 작업을 생성했는지 식별합니다. 인식되지 않는 유형의 경우 원본 판별식으로 폴백 |
2751| `status` | 현재 작업 상태 |2751| `status` | 현재 작업 상태 |
2759`session_crons`의 각 항목은 `CronCreate`, `ScheduleWakeup`, `/loop`에서 소싱된 하나의 세션 범위 예약된 깨어남을 설명합니다:2759`session_crons`의 각 항목은 `CronCreate`, `ScheduleWakeup`, `/loop`에서 소싱된 하나의 세션 범위 예약된 깨어남을 설명합니다:
2760 2760
2761| 필드 | 설명 |2761| 필드 | 설명 |
2762| :---------- | :--------------------------------------------------------------------- |2762| :- | :- |
2763| `id` | Cron 작업 식별자 |2763| `id` | Cron 작업 식별자 |
2764| `schedule` | Cron 표현식 (예: `0 9 * * 1-5`) |2764| `schedule` | Cron 표현식 (예: `0 9 * * 1-5`) |
2765| `recurring` | 일회성 깨어남의 경우 `false` (일정이 단일 발생 시간을 인코딩), 모든 일치에서 다시 발생하는 작업의 경우 `true` |2765| `recurring` | 일회성 깨어남의 경우 `false` (일정이 단일 발생 시간을 인코딩), 모든 일치에서 다시 발생하는 작업의 경우 `true` |
2803`Stop` 및 `SubagentStop` hook은 Claude가 계속할지 여부를 제어할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:2803`Stop` 및 `SubagentStop` hook은 Claude가 계속할지 여부를 제어할 수 있습니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 hook 스크립트는 이러한 이벤트 특정 필드를 반환할 수 있습니다:
2804 2804
2805| 필드 | 설명 |2805| 필드 | 설명 |
2806| :------------------------------------- | :------------------------------------------------------------------------------------------------------------- |2806| :- | :- |
2807| `decision` | `"block"`은 Claude가 중지되는 것을 방지합니다. 생략하여 Claude가 중지하도록 허용 |2807| `decision` | `"block"`은 Claude가 중지되는 것을 방지합니다. 생략하여 Claude가 중지하도록 허용 |
2808| `reason` | Claude가 중지되는 것이 차단될 때 필수입니다. Claude에 계속해야 하는 이유를 알립니다 |2808| `reason` | Claude가 중지되는 것이 차단될 때 필수입니다. Claude에 계속해야 하는 이유를 알립니다 |
2809| `hookSpecificOutput.additionalContext` | 비오류 피드백 Claude. 대화가 계속되므로 Claude가 이에 따라 행동할 수 있지만 `decision: "block"`과 달리 트랜스크립트에 hook 오류가 아닌 hook 피드백으로 표시됩니다 |2809| `hookSpecificOutput.additionalContext` | 비오류 피드백 Claude. 대화가 계속되므로 Claude가 이에 따라 행동할 수 있지만 `decision: "block"`과 달리 트랜스크립트에 hook 오류가 아닌 hook 피드백으로 표시됩니다 |
2841[공통 입력 필드](#common-input-fields) 외에도 StopFailure hook은 `error`, 선택적 `error_details`, 선택적 `last_assistant_message`를 받습니다. `error` 필드는 오류 유형을 식별하며 matcher 필터링에 사용됩니다.2841[공통 입력 필드](#common-input-fields) 외에도 StopFailure hook은 `error`, 선택적 `error_details`, 선택적 `last_assistant_message`를 받습니다. `error` 필드는 오류 유형을 식별하며 matcher 필터링에 사용됩니다.
2842 2842
2843| 필드 | 설명 |2843| 필드 | 설명 |
2844| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2844| :- | :- |
2845| `error` | 오류 유형: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, 또는 `unknown` |2845| `error` | 오류 유형: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, 또는 `unknown` |
2846| `error_details` | 사용 가능한 경우 오류에 대한 추가 세부 정보 |2846| `error_details` | 사용 가능한 경우 오류에 대한 추가 세부 정보 |
2847| `last_assistant_message` | 대화에 표시되는 렌더링된 오류 텍스트. `Stop` 및 `SubagentStop`과 달리 이 필드는 Claude의 대화형 출력을 보유하고 `StopFailure`의 경우 `"API Error: Rate limit reached"`와 같은 API 오류 문자열 자체를 포함합니다 |2847| `last_assistant_message` | 대화에 표시되는 렌더링된 오류 텍스트. `Stop` 및 `SubagentStop`과 달리 이 필드는 Claude의 대화형 출력을 보유하고 `StopFailure`의 경우 `"API Error: Rate limit reached"`와 같은 API 오류 문자열 자체를 포함합니다 |
2887```2887```
2888 2888
2889| 필드 | 설명 |2889| 필드 | 설명 |
2890| :-------------- | :------------------- |2890| :- | :- |
2891| `teammate_name` | 유휴 상태가 되려고 하는 팀원의 이름 |2891| `teammate_name` | 유휴 상태가 되려고 하는 팀원의 이름 |
2892| `team_name` | 팀의 이름 |2892| `team_name` | 팀의 이름 |
2893 2893
2924matcher는 구성 소스에서 필터링합니다:2924matcher는 구성 소스에서 필터링합니다:
2925 2925
2926| Matcher | 언제 발생하는지 |2926| Matcher | 언제 발생하는지 |
2927| :----------------- | :------------------------------------------------------ |2927| :- | :- |
2928| `user_settings` | `~/.claude/settings.json` 변경 |2928| `user_settings` | `~/.claude/settings.json` 변경 |
2929| `project_settings` | `.claude/settings.json` 변경 |2929| `project_settings` | `.claude/settings.json` 변경 |
2930| `local_settings` | `.claude/settings.local.json` 변경 |2930| `local_settings` | `.claude/settings.local.json` 변경 |
2975ConfigChange hook은 구성 변경이 적용되는 것을 차단할 수 있습니다. 종료 코드 2 또는 JSON `decision`을 사용하여 변경을 방지합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.2975ConfigChange hook은 구성 변경이 적용되는 것을 차단할 수 있습니다. 종료 코드 2 또는 JSON `decision`을 사용하여 변경을 방지합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.
2976 2976
2977| 필드 | 설명 |2977| 필드 | 설명 |
2978| :--------- | :------------------------------------------- |2978| :- | :- |
2979| `decision` | `"block"`은 구성 변경이 적용되는 것을 방지합니다. 생략하여 변경을 허용 |2979| `decision` | `"block"`은 구성 변경이 적용되는 것을 방지합니다. 생략하여 변경을 허용 |
2980| `reason` | 수락되지만 절대 표시되지 않음 |2980| `reason` | 수락되지만 절대 표시되지 않음 |
2981 2981
3024모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 CwdChanged hook은 `watchPaths`를 반환하여 [FileChanged](#filechanged)가 감시하는 파일 경로를 동적으로 설정할 수 있습니다:3024모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 CwdChanged hook은 `watchPaths`를 반환하여 [FileChanged](#filechanged)가 감시하는 파일 경로를 동적으로 설정할 수 있습니다:
3025 3025
3026| 필드 | 설명 |3026| 필드 | 설명 |
3027| :----------- | :---------------------------------------------------------------------------------------- |3027| :- | :- |
3028| `watchPaths` | 절대 경로의 배열. 현재 동적 감시 목록을 바꿉니다 (matcher 구성의 경로는 항상 감시됨). 새 디렉토리에 들어갈 때 빈 배열을 반환하는 것이 일반적입니다 |3028| `watchPaths` | 절대 경로의 배열. 현재 동적 감시 목록을 바꿉니다 (matcher 구성의 경로는 항상 감시됨). 새 디렉토리에 들어갈 때 빈 배열을 반환하는 것이 일반적입니다 |
3029 3029
3030CwdChanged hook은 결정 제어가 없습니다. 디렉토리 변경을 차단할 수 없습니다.3030CwdChanged hook은 결정 제어가 없습니다. 디렉토리 변경을 차단할 수 없습니다.
3050matcher는 디렉토리가 추가된 방식에 따라 필터링합니다:3050matcher는 디렉토리가 추가된 방식에 따라 필터링합니다:
3051 3051
3052| Matcher | 언제 발생하는지 |3052| Matcher | 언제 발생하는지 |
3053| :------------------- | :-------------------------------------------------- |3053| :- | :- |
3054| `slash_command` | `/add-dir`으로 디렉토리를 추가합니다 |3054| `slash_command` | `/add-dir`으로 디렉토리를 추가합니다 |
3055| `register_repo_root` | SDK 클라이언트가 `register_repo_root` 제어 요청으로 디렉토리를 추가합니다 |3055| `register_repo_root` | SDK 클라이언트가 `register_repo_root` 제어 요청으로 디렉토리를 추가합니다 |
3056 3056
3061[공통 입력 필드](#common-input-fields) 외에도 DirectoryAdded hook은 `directory` 및 `source`를 받습니다.3061[공통 입력 필드](#common-input-fields) 외에도 DirectoryAdded hook은 `directory` 및 `source`를 받습니다.
3062 3062
3063| 필드 | 설명 |3063| 필드 | 설명 |
3064| :---------- | :------------------------------------------------------------------------------------- |3064| :- | :- |
3065| `directory` | 추가된 디렉토리의 절대 경로 |3065| `directory` | 추가된 디렉토리의 절대 경로 |
3066| `source` | 디렉토리가 추가된 방식, `/add-dir`의 경우 `"slash_command"` 또는 SDK 제어 요청의 경우 `"register_repo_root"` |3066| `source` | 디렉토리가 추가된 방식, `/add-dir`의 경우 `"slash_command"` 또는 SDK 제어 요청의 경우 `"register_repo_root"` |
3067 3067
3135[공통 입력 필드](#common-input-fields) 외에도 FileChanged hook은 `file_path` 및 `event`를 받습니다.3135[공통 입력 필드](#common-input-fields) 외에도 FileChanged hook은 `file_path` 및 `event`를 받습니다.
3136 3136
3137| 필드 | 설명 |3137| 필드 | 설명 |
3138| :---------- | :--------------------------------------------------------------- |3138| :- | :- |
3139| `file_path` | 변경된 파일의 절대 경로 |3139| `file_path` | 변경된 파일의 절대 경로 |
3140| `event` | 발생한 일: `"change"` (파일 수정), `"add"` (파일 생성) 또는 `"unlink"` (파일 삭제) |3140| `event` | 발생한 일: `"change"` (파일 수정), `"add"` (파일 생성) 또는 `"unlink"` (파일 삭제) |
3141 3141
3157모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 FileChanged hook은 `watchPaths`를 반환하여 감시되는 파일 경로를 동적으로 업데이트할 수 있습니다:3157모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 FileChanged hook은 `watchPaths`를 반환하여 감시되는 파일 경로를 동적으로 업데이트할 수 있습니다:
3158 3158
3159| 필드 | 설명 |3159| 필드 | 설명 |
3160| :----------- | :---------------------------------------------------------------------------------------------------- |3160| :- | :- |
3161| `watchPaths` | 절대 경로의 배열. 현재 동적 감시 목록을 바꿉니다 (matcher 구성의 경로는 항상 감시됨). hook 스크립트가 변경된 파일을 기반으로 감시할 추가 파일을 발견할 때 사용합니다 |3161| `watchPaths` | 절대 경로의 배열. 현재 동적 감시 목록을 바꿉니다 (matcher 구성의 경로는 항상 감시됨). hook 스크립트가 변경된 파일을 기반으로 감시할 추가 파일을 발견할 때 사용합니다 |
3162 3162
3163FileChanged hook은 결정 제어가 없습니다. 파일 변경을 차단할 수 없습니다.3163FileChanged hook은 결정 제어가 없습니다. 파일 변경을 차단할 수 없습니다.
3291matcher 값은 압축이 수동으로 또는 자동으로 트리거되었는지 나타냅니다:3291matcher 값은 압축이 수동으로 또는 자동으로 트리거되었는지 나타냅니다:
3292 3292
3293| Matcher | 언제 발생하는지 |3293| Matcher | 언제 발생하는지 |
3294| :------- | :------------------------------------------------------------------------- |3294| :- | :- |
3295| `manual` | `/compact` |3295| `manual` | `/compact` |
3296| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달할 때 자동 압축 |3296| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달할 때 자동 압축 |
3297 3297
3327`PreCompact`와 동일한 matcher 값이 적용됩니다:3327`PreCompact`와 동일한 matcher 값이 적용됩니다:
3328 3328
3329| Matcher | 언제 발생하는지 |3329| Matcher | 언제 발생하는지 |
3330| :------- | :--------------------------------------------------------------------------- |3330| :- | :- |
3331| `manual` | `/compact` 후 |3331| `manual` | `/compact` 후 |
3332| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달할 때 자동 압축 후 |3332| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달할 때 자동 압축 후 |
3333 3333
3445[공통 입력 필드](#common-input-fields) 외에도 PreModelSwitch hook은 아래 표의 필드를 받습니다. 마지막 다섯 개는 새 모델로 대화를 다시 전송하는 비용을 설명하므로 hook은 전환이 발생하기 전에 해당 수치를 표시할 수 있습니다.3445[공통 입력 필드](#common-input-fields) 외에도 PreModelSwitch hook은 아래 표의 필드를 받습니다. 마지막 다섯 개는 새 모델로 대화를 다시 전송하는 비용을 설명하므로 hook은 전환이 발생하기 전에 해당 수치를 표시할 수 있습니다.
3446 3446
3447| 필드 | 유형 | 설명 |3447| 필드 | 유형 | 설명 |
3448| :-------------------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3448| :- | :- | :- |
3449| `from_model` | 문자열 | 전환 전의 모델 ID |3449| `from_model` | 문자열 | 전환 전의 모델 ID |
3450| `to_model` | 문자열 | 전환 후의 모델 ID. matcher는 이 모델의 정규 이름과 비교합니다 |3450| `to_model` | 문자열 | 전환 후의 모델 ID. matcher는 이 모델의 정규 이름과 비교합니다 |
3451| `requested_model` | 문자열 또는 `null` | 요청이 이름을 지정한 모델: `opus`와 같은 별칭, 전체 모델 ID, 또는 요청이 기본 모델인 경우 `null` |3451| `requested_model` | 문자열 또는 `null` | 요청이 이름을 지정한 모델: `opus`와 같은 별칭, 전체 모델 ID, 또는 요청이 기본 모델인 경우 `null` |
3485더 세밀한 제어를 위해 [PreToolUse](#pretooluse-decision-control)처럼 `hookSpecificOutput` 객체에서 `permissionDecision` 및 `permissionDecisionReason`을 반환합니다. `PreModelSwitch`는 `"allow"`, `"deny"`, `"ask"`를 수락합니다. `"defer"`, `updatedInput`, `additionalContext`는 수락하지 않습니다. 아래 표는 두 필드를 설명합니다:3485더 세밀한 제어를 위해 [PreToolUse](#pretooluse-decision-control)처럼 `hookSpecificOutput` 객체에서 `permissionDecision` 및 `permissionDecisionReason`을 반환합니다. `PreModelSwitch`는 `"allow"`, `"deny"`, `"ask"`를 수락합니다. `"defer"`, `updatedInput`, `additionalContext`는 수락하지 않습니다. 아래 표는 두 필드를 설명합니다:
3486 3486
3487| 필드 | 설명 |3487| 필드 | 설명 |
3488| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |3488| :- | :- |
3489| `permissionDecision` | `"allow"`는 진행하고 [prompt cache가 따뜻할 때 Claude Code가 표시하는 확인](/docs/ko/prompt-caching#switching-models)을 건너뜁니다. `"deny"`는 전환을 취소합니다. `"ask"`는 사용자에게 확인을 요청합니다 |3489| `permissionDecision` | `"allow"`는 진행하고 [prompt cache가 따뜻할 때 Claude Code가 표시하는 확인](/docs/ko/prompt-caching#switching-models)을 건너뜁니다. `"deny"`는 전환을 취소합니다. `"ask"`는 사용자에게 확인을 요청합니다 |
3490| `permissionDecisionReason` | `"deny"`의 경우 사용자에게 전환이 차단된 이유로 표시되거나 `set_model` 요청에 대한 오류로 반환됩니다. `"ask"`의 경우 확인 프롬프트에 표시됩니다. `"allow"`의 경우 무시됩니다 |3490| `permissionDecisionReason` | `"deny"`의 경우 사용자에게 전환이 차단된 이유로 표시되거나 `set_model` 요청에 대한 오류로 반환됩니다. `"ask"`의 경우 확인 프롬프트에 표시됩니다. `"allow"`의 경우 무시됩니다 |
3491 3491
3565Claude Code는 hook의 [일반 텍스트 stdout](#exit-code-0)을 종료 0에서 가져오거나 JSON 출력에서 `additionalContext`를 가져오고 전환 후 다음 요청과 함께 Claude에 전달합니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다:3565Claude Code는 hook의 [일반 텍스트 stdout](#exit-code-0)을 종료 0에서 가져오거나 JSON 출력에서 `additionalContext`를 가져오고 전환 후 다음 요청과 함께 Claude에 전달합니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다:
3566 3566
3567| 필드 | 설명 |3567| 필드 | 설명 |
3568| :------------------ | :------------------------------------------------------------------------------------- |3568| :- | :- |
3569| `additionalContext` | 다음 요청과 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |3569| `additionalContext` | 다음 요청과 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
3570 3570
3571다음 프롬프트를 보낸 후 5초 이내에 hook이 완료되지 않으면 Claude Code는 해당 출력 없이 그 요청을 보내고 대신 그다음 요청에 첨부합니다. 다음 요청 전에 모델이 여러 번 변경되면 Claude Code는 마지막 전환의 대상 모델에 대한 출력만 전달합니다.3571다음 프롬프트를 보낸 후 5초 이내에 hook이 완료되지 않으면 Claude Code는 해당 출력 없이 그 요청을 보내고 대신 그다음 요청에 첨부합니다. 다음 요청 전에 모델이 여러 번 변경되면 Claude Code는 마지막 전환의 대상 모델에 대한 출력만 전달합니다.
3579hook 입력의 `reason` 필드는 세션이 종료된 이유를 나타냅니다:3579hook 입력의 `reason` 필드는 세션이 종료된 이유를 나타냅니다:
3580 3580
3581| 이유 | 설명 |3581| 이유 | 설명 |
3582| :---------------------------- | :------------------------------------------------------------------- |3582| :- | :- |
3583| `clear` | `/clear` 명령으로 세션 지워짐 |3583| `clear` | `/clear` 명령으로 세션 지워짐 |
3584| `resume` | 대화형 `/resume`을 통해 세션 전환됨 |3584| `resume` | 대화형 `/resume`을 통해 세션 전환됨 |
3585| `logout` | 사용자 로그아웃 |3585| `logout` | 사용자 로그아웃 |
3685```3685```
3686 3686
3687| 필드 | 값 | 설명 |3687| 필드 | 값 | 설명 |
3688| :-------- | :---------------------------- | :---------------------------------------- |3688| :- | :- | :- |
3689| `action` | `accept`, `decline`, `cancel` | 요청을 수락, 거부 또는 취소할지 여부 |3689| `action` | `accept`, `decline`, `cancel` | 요청을 수락, 거부 또는 취소할지 여부 |
3690| `content` | 객체 | 제출할 form 필드 값. `action`이 `accept`일 때만 사용됨 |3690| `content` | 객체 | 제출할 form 필드 값. `action`이 `accept`일 때만 사용됨 |
3691 3691
3739```3739```
3740 3740
3741| 필드 | 값 | 설명 |3741| 필드 | 값 | 설명 |
3742| :-------- | :---------------------------- | :---------------------------------------------- |3742| :- | :- | :- |
3743| `action` | `accept`, `decline`, `cancel` | 사용자의 작업을 재정의합니다 |3743| `action` | `accept`, `decline`, `cancel` | 사용자의 작업을 재정의합니다 |
3744| `content` | 객체 | form 필드 값을 재정의합니다. `action`이 `accept`일 때만 의미 있음 |3744| `content` | 객체 | form 필드 값을 재정의합니다. `action`이 `accept`일 때만 의미 있음 |
3745 3745
3828```3828```
3829 3829
3830| 필드 | 필수 | 설명 |3830| 필드 | 필수 | 설명 |
3831| :---------------- | :-- | :----------------------------------------------------------------------------------------------------------------------------- |3831| :- | :- | :- |
3832| `type` | 예 | `"prompt"`여야 합니다 |3832| `type` | 예 | `"prompt"`여야 합니다 |
3833| `prompt` | 예 | LLM으로 전송할 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS` 사용. `$ARGUMENTS`가 없으면 입력 JSON이 프롬프트에 추가됩니다 |3833| `prompt` | 예 | LLM으로 전송할 프롬프트 텍스트. hook 입력 JSON에 대한 자리 표시자로 `$ARGUMENTS` 사용. `$ARGUMENTS`가 없으면 입력 JSON이 프롬프트에 추가됩니다 |
3834| `model` | 아니오 | 평가에 사용할 모델. 기본값은 빠른 모델입니다 |3834| `model` | 아니오 | 평가에 사용할 모델. 기본값은 빠른 모델입니다 |
3850```3850```
3851 3851
3852| 필드 | 설명 |3852| 필드 | 설명 |
3853| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |3853| :- | :- |
3854| `ok` | `true`는 허용합니다. `false`의 경우 아래의 이벤트별 동작을 참조하세요 |3854| `ok` | `true`는 허용합니다. `false`의 경우 아래의 이벤트별 동작을 참조하세요 |
3855| `reason` | `ok`가 `false`일 때 필수입니다 |3855| `reason` | `ok`가 `false`일 때 필수입니다 |
3856| `impossible` | 선택 사항입니다. 모델이 조건을 절대 만족할 수 없다고 판단할 때 `ok: false`와 함께 반환합니다. `Stop` 및 `SubagentStop`에서 Claude Code는 이유를 다시 피드백하는 대신 턴을 종료하도록 허용합니다. 에이전트 hook 및 기타 이벤트는 이를 무시합니다 |3856| `impossible` | 선택 사항입니다. 모델이 조건을 절대 만족할 수 없다고 판단할 때 `ok: false`와 함께 반환합니다. `Stop` 및 `SubagentStop`에서 Claude Code는 이유를 다시 피드백하는 대신 턴을 종료하도록 허용합니다. 에이전트 hook 및 기타 이벤트는 이를 무시합니다 |
