40| :- | :- |40| :- | :- |
41| `SessionStart` | 세션이 시작되거나 재개될 때 |41| `SessionStart` | 세션이 시작되거나 재개될 때 |
42| `Setup` | `--init-only`로 Claude Code를 시작하거나, `-p` 모드에서 `--init` 또는 `--maintenance`로 시작할 때. CI 또는 스크립트에서 일회성 준비를 위함 |42| `Setup` | `--init-only`로 Claude Code를 시작하거나, `-p` 모드에서 `--init` 또는 `--maintenance`로 시작할 때. CI 또는 스크립트에서 일회성 준비를 위함 |
43| `UserPromptSubmit` | 프롬프트를 제출할 때, Claude가 처리하기 전 |43| `UserPromptSubmit` | 프롬프트를 제출할 때, Claude가 처리하기 전. [Claude Code가 자체적으로 시작하는 턴](/docs/ko/hooks#userpromptsubmit)에서도 발생 |
44| `UserPromptExpansion` | 사용자가 입력한 명령이 프롬프트로 확장될 때, Claude에 도달하기 전. 확장을 차단할 수 있음 |44| `UserPromptExpansion` | 사용자가 입력한 명령이 프롬프트로 확장될 때, Claude에 도달하기 전. 확장을 차단할 수 있음 |
45| `PreToolUse` | 도구 호출이 실행되기 전. 차단할 수 있음 |45| `PreToolUse` | 도구 호출이 실행되기 전. 차단할 수 있음 |
46| `PermissionRequest` | 도구 호출이 권한 결정이 필요할 때 |46| `PermissionRequest` | 도구 호출이 권한 결정이 필요할 때 |
1159 훅 이벤트1159 훅 이벤트
1160</h2>1160</h2>
1161 1161
1162각 이벤트는 훅이 실행될 수 있는 Claude Code 수명 주기의 한 시점에 해당합니다. 아래 섹션은 세션 설정부터 에이전틱 루프를 거쳐 세션 종료까지 수명 주기 순서대로 정렬되어 있습니다. 각 섹션에서는 이벤트가 언제 발생하는지, 어떤 matcher를 지원하는지, 어떤 JSON 입력을 받는지, 출력을 통해 동작을 어떻게 제어하는지 설명합니다.1162각 이벤트는 Claude Code 수명 주기에서 훅이 실행될 수 있는 지점에 해당합니다. 아래 섹션은 세션 설정부터 에이전틱 루프를 거쳐 세션 종료까지 수명 주기 순서에 맞춰 정렬되어 있습니다. 각 섹션에서는 이벤트가 발생하는 시점, 지원하는 matcher, 수신하는 JSON 입력, 출력을 통해 동작을 제어하는 방법을 설명합니다.
1163 1163
1164<h3 id="sessionstart">1164<h3 id="sessionstart">
1165 SessionStart1165 SessionStart
1166</h3>1166</h3>
1167 1167
1168Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다. 기존 이슈나 코드베이스의 최근 변경 사항 같은 개발 컨텍스트를 로드하거나 환경 변수를 설정할 때 유용합니다. 스크립트가 필요하지 않은 정적 컨텍스트에는 대신 [CLAUDE.md](/docs/ko/memory)를 사용합니다.1168Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다. 기존 이슈나 코드베이스의 최근 변경 사항 같은 개발 컨텍스트를 불러오거나 환경 변수를 설정하는 데 유용합니다. 스크립트가 필요 없는 정적 컨텍스트에는 대신 [CLAUDE.md](/docs/ko/memory)를 사용합니다.
1169 1169
1170SessionStart는 모든 세션에서 실행되므로 이 훅은 빠르게 유지해야 합니다. `type: "command"` 및 `type: "mcp_tool"` 훅만 지원됩니다. `mcp_tool` 훅이 언제 실행되는지는 [MCP 도구 훅 필드](#mcp-tool-hook-fields)를 참조하십시오.1170SessionStart는 모든 세션에서 실행되므로 이 훅은 빠르게 유지해야 합니다. `type: "command"` 및 `type: "mcp_tool"` 훅만 지원됩니다. `mcp_tool` 훅이 실행되는 시점은 [MCP 도구 훅 필드](#mcp-tool-hook-fields)를 참조하세요.
1171 1171
1172matcher 값은 세션이 시작된 방식에 해당합니다.1172matcher 값은 세션이 시작된 방식에 해당합니다.
1173 1173
1181 1181
1182v2.1.214 이전에는 분기된 세션이 source를 `"resume"`으로 보고했습니다.1182v2.1.214 이전에는 분기된 세션이 source를 `"resume"`으로 보고했습니다.
1183 1183
1184대화형 세션을 시작하거나, 실행 시 `--continue` 또는 `--resume`으로 대화를 재개하거나, `/clear`를 실행하면 SessionStart 훅이 백그라운드에서 실행됩니다. 바로 입력할 수 있으며, 재개한 대화는 훅을 기다리지 않고 표시됩니다. Claude의 첫 응답은 여전히 훅이 완료될 때까지 기다리므로 훅의 컨텍스트가 Claude에게 전달됩니다.1184대화형 세션을 시작하거나, 실행 시 `--continue` 또는 `--resume`으로 대화를 재개하거나, `/clear`를 실행하면 SessionStart 훅이 백그라운드에서 실행됩니다. 바로 입력을 시작할 수 있으며, 재개한 대화는 훅을 기다리지 않고 표시됩니다. Claude의 첫 응답은 여전히 훅이 끝날 때까지 기다리므로 훅의 컨텍스트가 Claude에 전달됩니다.
1185 1185
1186세션 내에서 `/resume`으로 대화를 전환하면 대신 전환이 훅 완료를 기다립니다. 백그라운드 훅이 아직 실행 중일 때 `/clear`를 실행하거나 다른 대화로 전환하면 훅이 반환하는 내용은 세션에 적용되지 않습니다.1186세션 안에서 `/resume`으로 대화를 전환하면 전환이 대신 훅이 끝날 때까지 기다립니다. 백그라운드 훅이 아직 실행 중일 때 `/clear`를 실행하거나 다른 대화로 전환하면 훅이 반환하는 내용은 세션에 적용되지 않습니다.
1187 1187
1188재개한 세션을 포함하여 실행 시에도 동일한 대기가 적용됩니다. SessionStart 훅이 아직 실행 중일 때 보낸 프롬프트는 훅이 완료될 때까지 Claude에게 전달되지 않습니다.1188재개한 세션을 포함하여 실행 시에도 동일한 대기가 적용됩니다. SessionStart 훅이 아직 실행 중일 때 보낸 프롬프트는 훅이 끝날 때까지 Claude에 전달되지 않습니다.
1189 1189
1190어느 쪽 대기 중이든 `Esc`를 누르면 프롬프트를 보내지 않고 입력란으로 되돌릴 수 있습니다. 훅은 계속 실행됩니다.1190어느 대기 중이든 `Esc`를 누르면 프롬프트를 보내지 않고 입력란으로 되돌릴 수 있습니다. 훅은 계속 실행됩니다.
1191 1191
1192<h4 id="sessionstart-input">1192<h4 id="sessionstart-input">
1193 SessionStart 입력1193 SessionStart 입력
1194</h4>1194</h4>
1195 1195
1196[공통 입력 필드](#common-input-fields) 외에도 SessionStart 훅은 `source`와 선택적으로 `model`, `agent_type`, `session_title`을 받습니다.1196[공통 입력 필드](#common-input-fields) 외에도 SessionStart 훅은 `source`와 선택적으로 `model`, `agent_type`, `session_title`을 수신합니다.
1197 1197
1198| 필드 | 설명 |1198| 필드 | 설명 |
1199| :- | :- |1199| :- | :- |
1200| `source` | 세션이 시작된 방식: 새 세션은 `"startup"`, 재개된 세션은 `"resume"`, `/clear` 후에는 `"clear"`, 압축 후에는 `"compact"`, 기존 세션에서 분기된 새 세션은 `"fork"` |1200| `source` | 세션이 시작된 방식: 새 세션은 `"startup"`, 재개된 세션은 `"resume"`, `/clear` 이후는 `"clear"`, 압축 이후는 `"compact"`, 기존 세션에서 분기된 새 세션은 `"fork"` |
1201| `model` | 활성 모델 식별자입니다. 예를 들어 `/clear` 후나 대화 복구를 통해 세션이 복원된 경우에는 생략될 수 있으므로 읽기 전에 필드가 있는지 확인해야 합니다 |1201| `model` | 활성 모델 식별자. 예를 들어 `/clear` 이후나 대화 복구를 통해 세션이 복원된 경우 생략될 수 있으므로, 읽기 전에 필드가 있는지 확인해야 합니다 |
1202| `agent_type` | 에이전트 이름입니다. `claude --agent <name>`으로 Claude Code를 시작한 경우에 존재합니다 |1202| `agent_type` | 에이전트 이름. `claude --agent <name>`으로 Claude Code를 시작할 때 포함됩니다 |
1203| `session_title` | 세션의 사용자 지정 제목입니다. 예를 들어 `--name`, `/rename`, 훅의 `sessionTitle` 출력 또는 Agent SDK의 `renameSession()`으로 제목이 설정된 경우에 존재합니다. `sessionTitle`을 내보내는 훅은 기존 사용자 지정 제목을 덮어쓰지 않도록 먼저 이 필드를 확인할 수 있습니다 |1203| `session_title` | 세션의 사용자 지정 제목. 예를 들어 `--name`, `/rename`, 훅의 `sessionTitle` 출력 또는 Agent SDK의 `renameSession()`으로 제목이 설정된 경우 포함됩니다. `sessionTitle`을 내보내는 훅은 기존 사용자 지정 제목을 덮어쓰지 않도록 이 필드를 먼저 확인할 수 있습니다 |
1204 1204
1205이름을 지정하지 않은 세션에도 [생성된 제목](/docs/ko/sessions#name-your-sessions)이 있을 수 있습니다. 이 제목은 사용자 지정 제목이 아니며 `session_title`에 나타나지 않습니다.1205이름을 지정하지 않은 세션에도 [생성된 제목](/docs/ko/sessions#name-your-sessions)이 있을 수 있습니다. 이 제목은 사용자 지정 제목이 아니며 `session_title`에 나타나지 않습니다.
1206 1206
1207`source`가 `"resume"` 또는 `"fork"`이고 트랜스크립트에 Claude의 응답이 하나 이상 포함된 경우, SessionStart 훅은 아래 네 가지 필드도 받습니다. 훅은 이 필드를 사용하여 첫 요청 전에 오래된 대화를 재개하는 데 드는 비용을 보고할 수 있으며, 예를 들어 [`systemMessage`](#json-output)로 보고할 수 있습니다. 이 필드를 사용하려면 Claude Code v2.1.251 이상이 필요합니다.1207`source`가 `"resume"` 또는 `"fork"`이고 트랜스크립트에 Claude의 응답이 하나 이상 포함되어 있으면 SessionStart 훅은 아래 네 가지 필드도 수신합니다. 훅은 이 필드를 사용하여 오래된 대화를 재개하는 데 드는 비용을 첫 요청 전에 보고할 수 있습니다. 예를 들어 [`systemMessage`](#json-output)에 보고할 수 있습니다. 이 필드에는 Claude Code v2.1.251 이상이 필요합니다.
1208 1208
1209| 필드 | 설명 |1209| 필드 | 설명 |
1210| :- | :- |1210| :- | :- |
1211| `seconds_since_last_response` | 재개된 트랜스크립트의 마지막 응답 이후 경과한 실제 시간(초) |1211| `seconds_since_last_response` | 재개된 트랜스크립트의 마지막 응답 이후 경과한 실제 시간(초) |
1212| `context_tokens` | 재개된 세션의 첫 요청이 프롬프트로 다시 보내는 토큰 |1212| `context_tokens` | 재개된 세션의 첫 요청이 프롬프트로 다시 보내는 토큰 수 |
1213| `prompt_cache_likely_expired` | 마지막 응답이 세션의 [프롬프트 캐시 수명](/docs/ko/prompt-caching#cache-lifetime)보다 오래되었거나 이후의 압축이 캐시된 대화를 대체한 경우 `true` |1213| `prompt_cache_likely_expired` | 마지막 응답이 세션의 [프롬프트 캐시 수명](/docs/ko/prompt-caching#cache-lifetime)보다 오래되었거나 이후의 압축이 캐시된 대화를 대체한 경우 `true` |
1214| `estimated_cache_write_usd` | 세션의 모델에서 `context_tokens`를 프롬프트 캐시에 쓰는 데 드는 예상 비용(미국 달러)이며, 응답은 제외됩니다 |1214| `estimated_cache_write_usd` | 세션의 모델에서 `context_tokens`를 프롬프트 캐시에 쓰는 예상 비용(미국 달러). 응답은 제외됩니다 |
1215 1215
1216다음 예시는 마지막 응답 90분 후에 재개된 세션의 입력을 보여 줍니다.1216다음 예시는 마지막 응답 후 90분 뒤에 재개된 세션의 입력을 보여 줍니다.
1217 1217
1218```json theme={null}1218```json theme={null}
1219{1219{
1234 SessionStart 결정 제어1234 SessionStart 결정 제어
1235</h4>1235</h4>
1236 1236
1237Claude Code는 [일반 텍스트로 취급하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 다음 이벤트별 필드를 반환할 수 있습니다.1237Claude Code는 [일반 텍스트로 처리하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 다음과 같은 이벤트별 필드를 반환할 수 있습니다.
1238 1238
1239| 필드 | 설명 |1239| 필드 | 설명 |
1240| :- | :- |1240| :- | :- |
1241| `additionalContext` | 대화 시작 시 첫 프롬프트 전에 Claude의 컨텍스트에 추가되는 문자열입니다. 텍스트가 전달되는 방식과 넣을 내용은 [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |1241| `additionalContext` | 첫 프롬프트 전, 대화 시작 시점에 Claude의 컨텍스트에 추가되는 문자열. 텍스트가 전달되는 방식과 포함할 내용은 [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
1242| `initialUserMessage` | 세션의 첫 사용자 메시지로 사용되는 문자열입니다. `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에 적용되며, 프롬프트가 제공되지 않아도 첫 턴이 됩니다. 프롬프트가 제공되면 그 프롬프트가 다음 턴으로 이어집니다. 기존 턴에 첨부되는 `additionalContext`와 달리 이 필드는 턴을 생성합니다 |1242| `initialUserMessage` | 세션의 첫 사용자 메시지로 사용되는 문자열. `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에 적용되며, 프롬프트가 제공되지 않아도 첫 턴이 됩니다. 프롬프트가 제공되면 그 프롬프트가 다음 턴으로 이어집니다. 기존 턴에 첨부되는 `additionalContext`와 달리 이 필드는 턴을 생성합니다 |
1243| `sessionTitle` | 세션 제목을 설정하며, `/rename`과 같은 효과가 있습니다. 실행 폴더, git 브랜치 또는 worktree 이름으로 세션 이름을 자동 지정할 때 사용합니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용되며, `"clear"` 및 `"compact"`에서는 무시됩니다 |1243| `sessionTitle` | 세션 제목을 설정하며, `/rename`과 효과가 같습니다. 실행 폴더, git 브랜치 또는 worktree 이름으로 세션 이름을 자동으로 지정하는 데 사용합니다. `source`가 `"startup"`, `"resume"` 또는 `"fork"`일 때 적용되며, `"clear"`와 `"compact"`에서는 무시됩니다 |
1244| `watchPaths` | 이 세션 동안 [FileChanged](#filechanged) 이벤트를 감시할 절대 경로의 배열 |1244| `watchPaths` | 이 세션 동안 [FileChanged](#filechanged) 이벤트를 감시할 절대 경로 배열 |
1245| `reloadSkills` | 불리언입니다. `true`이면 Claude Code는 SessionStart 훅이 완료된 후 [스킬](/docs/ko/skills) 및 명령 디렉터리를 다시 스캔하므로, 훅이 설치한 스킬을 첫 프롬프트부터 같은 세션에서 사용할 수 있습니다 |1245| `reloadSkills` | 불리언. `true`이면 SessionStart 훅이 완료된 후 Claude Code가 [스킬](/docs/ko/skills) 및 명령 디렉터리를 다시 스캔하므로, 훅이 설치한 스킬을 첫 프롬프트부터 같은 세션에서 사용할 수 있습니다 |
1246 1246
1247```json theme={null}1247```json theme={null}
1248{1248{
1254}1254}
1255```1255```
1256 1256
1257이 이벤트에서는 일반 stdout이 이미 Claude에게 전달되므로, 컨텍스트만 로드하는 훅은 JSON을 만들지 않고 stdout에 직접 출력할 수 있습니다. 컨텍스트를 `sessionTitle` 같은 다른 필드와 결합해야 할 때 JSON 형식을 사용합니다.1257이 이벤트에서는 일반 stdout이 이미 Claude에 전달되므로, 컨텍스트만 불러오는 훅은 JSON을 구성하지 않고 stdout에 직접 출력할 수 있습니다. 컨텍스트를 `sessionTitle` 같은 다른 필드와 함께 사용해야 할 때 JSON 형식을 사용합니다.
1258 1258
1259SessionStart 훅이 스킬을 설치하거나 업데이트할 때는 `reloadSkills`를 사용합니다. 스킬 검색은 일반적으로 SessionStart 훅이 완료되기 전에 실행되므로, 그렇지 않으면 훅이 `~/.claude/skills/` 또는 `.claude/skills/`에 쓴 파일은 다음 세션에서만 나타납니다. 다음 예시는 공유 스킬 저장소를 동기화하고 다시 스캔을 요청합니다.1259SessionStart 훅이 스킬을 설치하거나 업데이트할 때는 `reloadSkills`를 사용합니다. 스킬 검색은 일반적으로 SessionStart 훅이 끝나기 전에 실행되므로, 그렇지 않으면 훅이 `~/.claude/skills/` 또는 `.claude/skills/`에 작성한 파일은 다음 세션에서만 나타납니다. 다음 예시는 공유 스킬 저장소를 동기화하고 다시 스캔을 요청합니다.
1260 1260
1261```bash theme={null}1261```bash theme={null}
1262#!/bin/bash1262#!/bin/bash
1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1268```1268```
1269 1269
1270저장소 URL은 자리 표시자이므로 사용자의 스킬 저장소로 바꿔야 합니다. 자리 표시자를 그대로 사용하면 clone이 실패하고 stderr에 `fatal:` 메시지가 출력됩니다. 0으로 종료하는 SessionStart 훅의 stderr는 정보 제공용일 뿐이므로 `reloadSkills` 요청은 여전히 적용됩니다.1270저장소 URL은 자리 표시자이므로 자체 스킬 저장소로 바꿔야 합니다. 자리 표시자를 그대로 두면 clone이 실패하고 stderr에 `fatal:` 메시지가 출력됩니다. 0으로 종료하는 SessionStart 훅의 stderr는 정보 제공용일 뿐이므로 `reloadSkills` 요청은 여전히 적용됩니다.
1271 1271
1272<h4 id="persist-environment-variables">1272<h4 id="persist-environment-variables">
1273 환경 변수 유지1273 환경 변수 유지
1274</h4>1274</h4>
1275 1275
1276SessionStart 훅은 `CLAUDE_ENV_FILE` 환경 변수에 접근할 수 있으며, 이 변수는 이후 Bash 명령을 위해 환경 변수를 유지할 수 있는 파일 경로를 제공합니다.1276SessionStart 훅은 `CLAUDE_ENV_FILE` 환경 변수에 액세스할 수 있습니다. 이 변수는 이후 Bash 명령에 사용할 환경 변수를 유지할 수 있는 파일 경로를 제공합니다.
1277 1277
1278개별 환경 변수를 설정하려면 `CLAUDE_ENV_FILE`에 `export` 문을 씁니다. 다른 훅이 설정한 변수를 보존하려면 추가(`>>`)를 사용합니다.1278개별 환경 변수를 설정하려면 `export` 문을 `CLAUDE_ENV_FILE`에 작성합니다. 다른 훅이 설정한 변수를 보존하려면 추가(`>>`)를 사용합니다.
1279 1279
1280```bash theme={null}1280```bash theme={null}
1281#!/bin/bash1281#!/bin/bash
1289exit 01289exit 0
1290```1290```
1291 1291
1292설정 명령의 모든 환경 변경 사항을 캡처하려면 전후의 내보낸 변수를 비교합니다.1292설정 명령으로 인한 모든 환경 변경 사항을 캡처하려면 전후의 내보낸 변수를 비교합니다.
1293 1293
1294```bash theme={null}1294```bash theme={null}
1295#!/bin/bash1295#!/bin/bash
1309```1309```
1310 1310
1311<Note>1311<Note>
1312 `CLAUDE_ENV_FILE`은 SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), [FileChanged](#filechanged) 훅에서 사용할 수 있습니다. 다른 훅 유형은 이 변수에 접근할 수 없습니다.1312 `CLAUDE_ENV_FILE`은 SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), [FileChanged](#filechanged) 훅에서 사용할 수 있습니다. 다른 훅 유형은 이 변수에 액세스할 수 없습니다.
1313</Note>1313</Note>
1314 1314
1315<h3 id="setup">1315<h3 id="setup">
1325| `init` | `claude --init-only` 또는 `claude -p --init` |1325| `init` | `claude --init-only` 또는 `claude -p --init` |
1326| `maintenance` | `claude -p --maintenance` |1326| `maintenance` | `claude -p --maintenance` |
1327 1327
1328`claude --init-only`를 실행하면 Claude Code는 Setup 훅과 `startup` matcher를 사용하는 `SessionStart` 훅을 실행한 다음, 대화를 시작하지 않고 종료합니다.1328`claude --init-only`를 실행하면 Claude Code는 Setup 훅과 `startup` matcher를 사용하는 `SessionStart` 훅을 실행한 다음 대화를 시작하지 않고 종료합니다.
1329 1329
1330`-p`로 대화를 시작하거나 계속할 때는 인수로 또는 stdin 파이프로 프롬프트도 제공해야 합니다. `SessionStart` 훅이 [`initialUserMessage`](#sessionstart-decision-control)를 제공하거나 [지연된 도구 호출](#defer-a-tool-call-for-later)이 있는 세션을 재개할 때는 프롬프트를 생략할 수 있습니다.1330`-p`로 대화를 시작하거나 계속하는 경우 프롬프트도 인수로 제공하거나 stdin으로 파이프해야 합니다. `SessionStart` 훅이 [`initialUserMessage`](#sessionstart-decision-control)를 제공하거나 [지연된 도구 호출](#defer-a-tool-call-for-later)이 있는 세션을 재개하는 경우에는 프롬프트를 생략할 수 있습니다.
1331 1331
1332성공하면 `--init-only`는 터미널에 아무것도 출력하지 않습니다. 훅이 실행되었는지 확인하려면 `<path>`를 로그 파일 위치로 바꿔 `claude --debug-file <path> --init-only`로 시작하고, 로그에서 Setup 및 SessionStart 훅 항목을 확인합니다.1332성공하면 `--init-only`는 터미널에 아무것도 출력하지 않습니다. 훅이 실행되었는지 확인하려면 `<path>`를 로그 파일 위치로 바꿔 `claude --debug-file <path> --init-only`로 시작한 다음, 로그에서 Setup 및 SessionStart 훅 항목을 확인합니다.
1333 1333
1334Setup은 매번 실행될 때 발생하지 않으므로, 의존성 설치가 필요한 플러그인은 Setup에만 의존할 수 없습니다. 실용적인 패턴은 처음 사용할 때 의존성을 확인하고 없으면 설치하는 것입니다. 예를 들어 `${CLAUDE_PLUGIN_DATA}/node_modules`가 있는지 테스트하고 없으면 `npm install`을 실행하는 훅이나 스킬을 사용할 수 있습니다. 설치된 의존성을 저장할 위치는 [영구 데이터 디렉터리](/docs/ko/plugins/components#path-variables-and-persistent-data)를 참조하십시오. 마켓플레이스를 통해 플러그인을 배포하는 경우에는 이 패턴이 필요하지 않을 수 있습니다. Claude Code는 플러그인을 캐시할 때 [적격한 Node.js 패키지 의존성을 자동으로 설치](/docs/ko/plugins/loading#node-js-package-dependencies)합니다.1334Setup은 매번 실행 시 발생하지 않으므로, 의존성 설치가 필요한 플러그인은 Setup에만 의존할 수 없습니다. 실용적인 패턴은 처음 사용할 때 의존성을 확인하고 없으면 설치하는 것입니다. 예를 들어 훅이나 스킬이 `${CLAUDE_PLUGIN_DATA}/node_modules`가 있는지 확인하고 없으면 `npm install`을 실행할 수 있습니다. 설치된 의존성을 저장할 위치는 [영구 데이터 디렉터리](/docs/ko/plugins/components#path-variables-and-persistent-data)를 참조하세요. 마켓플레이스를 통해 플러그인을 배포하는 경우에는 이 패턴이 필요하지 않을 수 있습니다. Claude Code는 플러그인을 캐시할 때 [적격한 Node.js 패키지 의존성을 자동으로 설치](/docs/ko/plugins/loading#node-js-package-dependencies)합니다.
1335 1335
1336<h4 id="setup-input">1336<h4 id="setup-input">
1337 Setup 입력1337 Setup 입력
1338</h4>1338</h4>
1339 1339
1340[공통 입력 필드](#common-input-fields) 외에도 Setup 훅은 `"init"` 또는 `"maintenance"`로 설정된 `trigger` 필드를 받습니다.1340[공통 입력 필드](#common-input-fields) 외에도 Setup 훅은 `"init"` 또는 `"maintenance"`로 설정된 `trigger` 필드를 수신합니다.
1341 1341
1342```json theme={null}1342```json theme={null}
1343{1343{
1353 Setup 결정 제어1353 Setup 결정 제어
1354</h4>1354</h4>
1355 1355
1356Setup 훅은 차단할 수 없으며, 어떤 종료 코드에서도 실행이 계속됩니다. 모든 종료 코드에서 Claude Code는 `systemMessage`, `continue`, `hookSpecificOutput.additionalContext` 같은 Setup 훅의 [JSON 출력 필드](#json-output)를 버립니다. `-p`를 사용하면 Setup 훅의 stdout, stderr, 종료 코드는 `--output-format stream-json --verbose`로 실행한 경우에만 실행 출력에 [`hook_response` 이벤트](/docs/ko/headless#read-session-metadata)로 나타납니다.1356Setup 훅은 차단할 수 없으며, 종료 코드와 관계없이 실행이 계속됩니다. 모든 종료 코드에서 Claude Code는 `systemMessage`, `continue`, `hookSpecificOutput.additionalContext` 같은 Setup 훅의 [JSON 출력 필드](#json-output)를 버립니다. `-p`를 사용하는 경우 Setup 훅의 stdout, stderr, 종료 코드는 `--output-format stream-json --verbose`로 실행할 때만 실행 출력에 [`hook_response` 이벤트](/docs/ko/headless#read-session-metadata)로 나타납니다.
1357 1357
1358Setup 훅은 `CLAUDE_ENV_FILE`에 접근할 수 있습니다. 해당 파일에 쓴 변수는 [SessionStart 훅](#persist-environment-variables)과 마찬가지로 세션의 이후 Bash 명령에 유지됩니다. `Setup`에서는 `type: "command"` 훅만 실행됩니다. `Setup`의 `type: "mcp_tool"` 훅은 [MCP 도구 훅 필드](#mcp-tool-hook-fields)에 설명된 대로 항상 건너뜁니다.1358Setup 훅은 `CLAUDE_ENV_FILE`에 액세스할 수 있습니다. 이 파일에 작성한 변수는 [SessionStart 훅](#persist-environment-variables)과 마찬가지로 세션의 이후 Bash 명령에 유지됩니다. `Setup`에서는 `type: "command"` 훅만 실행됩니다. `Setup`의 `type: "mcp_tool"` 훅은 [MCP 도구 훅 필드](#mcp-tool-hook-fields)에 설명된 대로 항상 건너뜁니다.
1359 1359
1360<h3 id="instructionsloaded">1360<h3 id="instructionsloaded">
1361 InstructionsLoaded1361 InstructionsLoaded
1362</h3>1362</h3>
1363 1363
1364`CLAUDE.md` 또는 `.claude/rules/*.md` 파일이 컨텍스트에 로드될 때 발생합니다. 이 이벤트는 세션 시작 시 즉시 로드되는 파일에 대해 발생하고, 이후 파일이 지연 로드될 때 다시 발생합니다. 예를 들어 Claude가 중첩된 `CLAUDE.md`가 포함된 하위 디렉터리에 접근하거나 `paths:` frontmatter가 있는 조건부 규칙이 일치할 때입니다. 이 훅은 차단이나 결정 제어를 지원하지 않습니다. 관찰 가능성을 위해 비동기적으로 실행됩니다.1364`CLAUDE.md` 또는 `.claude/rules/*.md` 파일이 컨텍스트에 로드될 때 발생합니다. 이 이벤트는 즉시 로드되는 파일에 대해 세션 시작 시 발생하며, 이후 파일이 지연 로드될 때 다시 발생합니다. 예를 들어 Claude가 중첩된 `CLAUDE.md`가 있는 하위 디렉터리에 액세스하거나 `paths:` frontmatter가 있는 조건부 규칙이 일치할 때입니다. 이 훅은 차단이나 결정 제어를 지원하지 않습니다. 관측 가능성을 위해 비동기적으로 실행됩니다.
1365 1365
1366이 이벤트는 Claude가 **Project instructions** 설정을 통해 [`AGENTS.md`를 직접 읽을](/docs/ko/memory#agents-md) 때는 발생하지 않습니다. `CLAUDE.md`가 `AGENTS.md`를 가져올 때는 다른 가져온 파일과 마찬가지로 `load_reason`이 `include`로 설정되어 발생하며, `CLAUDE.md`가 해당 파일에 대한 심볼릭 링크일 때는 일반 `CLAUDE.md` 로드로 발생합니다.1366이 이벤트는 Claude가 **Project instructions** 설정을 통해 [`AGENTS.md`를 직접 읽을](/docs/ko/memory#agents-md) 때는 발생하지 않습니다. `CLAUDE.md`가 `AGENTS.md`를 가져오는 경우에는 다른 가져온 파일과 마찬가지로 `load_reason`이 `include`로 설정되어 발생하며, `CLAUDE.md`가 해당 파일에 대한 심볼릭 링크인 경우에는 일반적인 `CLAUDE.md` 로드로 발생합니다.
1367 1367
1368matcher는 `load_reason`에 대해 실행됩니다. 예를 들어 세션 시작 시 로드된 파일에 대해서만 발생시키려면 `"matcher": "session_start"`를, 지연 로드에 대해서만 발생시키려면 `"matcher": "path_glob_match|nested_traversal"`을 사용합니다.1368matcher는 `load_reason`에 대해 실행됩니다. 예를 들어 세션 시작 시 로드된 파일에 대해서만 발생시키려면 `"matcher": "session_start"`를, 지연 로드에 대해서만 발생시키려면 `"matcher": "path_glob_match|nested_traversal"`을 사용합니다.
1369 1369
1371 InstructionsLoaded 입력1371 InstructionsLoaded 입력
1372</h4>1372</h4>
1373 1373
1374[공통 입력 필드](#common-input-fields) 외에도 InstructionsLoaded 훅은 다음 필드를 받습니다.1374[공통 입력 필드](#common-input-fields) 외에도 InstructionsLoaded 훅은 다음 필드를 수신합니다.
1375 1375
1376| 필드 | 설명 |1376| 필드 | 설명 |
1377| :- | :- |1377| :- | :- |
1378| `file_path` | 로드된 지침 파일의 절대 경로 |1378| `file_path` | 로드된 지침 파일의 절대 경로 |
1379| `memory_type` | 파일의 범위: `"User"`, `"Project"`, `"Local"` 또는 `"Managed"` |1379| `memory_type` | 파일의 범위: `"User"`, `"Project"`, `"Local"` 또는 `"Managed"` |
1380| `load_reason` | 파일이 로드된 이유: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` 또는 `"compact"`. `"compact"` 값은 압축 이벤트 후 지침 파일이 다시 로드될 때 발생합니다 |1380| `load_reason` | 파일이 로드된 이유: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` 또는 `"compact"`. `"compact"` 값은 압축 이벤트 후 지침 파일이 다시 로드될 때 발생합니다 |
1381| `globs` | 파일의 `paths:` frontmatter에 있는 경로 glob 패턴(있는 경우). `path_glob_match` 로드에만 존재합니다 |1381| `globs` | 파일의 `paths:` frontmatter에 있는 경로 glob 패턴(있는 경우). `path_glob_match` 로드에만 포함됩니다 |
1382| `trigger_file_path` | 지연 로드의 경우, 접근하여 이 로드를 트리거한 파일의 경로 |1382| `trigger_file_path` | 지연 로드의 경우, 액세스하여 이 로드를 트리거한 파일의 경로 |
1383| `parent_file_path` | `include` 로드의 경우, 이 파일을 포함한 상위 지침 파일의 경로 |1383| `parent_file_path` | `include` 로드의 경우, 이 파일을 포함한 상위 지침 파일의 경로 |
1384 1384
1385```json theme={null}1385```json theme={null}
1398 InstructionsLoaded 결정 제어1398 InstructionsLoaded 결정 제어
1399</h4>1399</h4>
1400 1400
1401InstructionsLoaded 훅에는 결정 제어가 없습니다. 지침 로드를 차단하거나 수정할 수 없습니다. Claude Code는 `systemMessage`, `continue` 같은 [JSON 출력 필드](#json-output)를 버립니다. 이 이벤트는 감사 로깅, 규정 준수 추적 또는 관찰 가능성에 사용합니다.1401InstructionsLoaded 훅에는 결정 제어가 없습니다. 지침 로드를 차단하거나 수정할 수 없습니다. Claude Code는 `systemMessage`, `continue` 같은 [JSON 출력 필드](#json-output)를 버립니다. 이 이벤트는 감사 로깅, 규정 준수 추적 또는 관측 가능성에 사용합니다.
1402 1402
1403<h3 id="userpromptsubmit">1403<h3 id="userpromptsubmit">
1404 UserPromptSubmit1404 UserPromptSubmit
1405</h3>1405</h3>
1406 1406
1407사용자가 프롬프트를 제출하면 Claude가 처리하기 전에 실행됩니다. 이를 통해1407프롬프트가 제출된 후 Claude가 처리하기 전에 실행됩니다. 이를 통해
1408프롬프트나 대화를 기반으로 추가 컨텍스트를 더하거나, 프롬프트를 검증하거나,1408프롬프트/대화를 기반으로 추가 컨텍스트를 추가하거나, 프롬프트를 검증하거나,
1409특정 유형의 프롬프트를 차단할 수 있습니다.1409특정 유형의 프롬프트를 차단할 수 있습니다.
1410 1410
1411`UserPromptSubmit` 훅의 기본 타임아웃은 `command`, `http`, `mcp_tool` 유형에서 30초이며, 대부분의 다른 이벤트에서 이 유형들의 기본값인 600초보다 짧습니다. 이 훅은 모든 프롬프트 전에 실행되고 완료될 때까지 모델 처리를 차단하므로, 멈춘 훅은 세션을 정지시킵니다. 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정합니다.1411`UserPromptSubmit` 훅은 사용자가 입력한 프롬프트에서만 발생하는 것이 아닙니다. Claude Code는 다음 경우에도 이 훅을 실행합니다.
1412 1412
1413[`async: true`](#run-hooks-in-the-background)로 실행하는 명령 훅을 제외하고, 타임아웃에 도달한 `UserPromptSubmit` 명령, HTTP 또는 MCP 도구 훅은 취소되며 `additionalContext`를 포함한 출력이 버려집니다. 프롬프트는 해당 컨텍스트 없이 여전히 Claude에게 전달됩니다. 트랜스크립트에는 훅 이름, 발생한 타임아웃, 출력이 버려졌다는 알림이 표시됩니다.1413* `/loop` 반복을 포함해 [예약 작업](/docs/ko/scheduled-tasks)이 실행될 때
1414* [백그라운드 서브에이전트](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)가 자신을 시작한 세션에 결과를 보고할 때
1415* [다른 세션이 보낸 메시지](/docs/ko/cross-session-messaging)가 메인 대화에 도착할 때
1414 1416
1415`UserPromptSubmit`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃에 도달하면 훅 이름과 타임아웃을 명시한 메시지와 함께 프롬프트를 차단합니다. 해당 위치의 콜백은 실패 시 열려서는 안 되는 정책 게이트 역할을 할 수 있기 때문입니다. 세션은 계속됩니다. v2.1.208 이전에는 해당 이벤트에서 콜백 타임아웃이 발생하면 실행 오류로 턴이 종료되었습니다.1417`UserPromptSubmit` 훅의 기본 타임아웃은 `command`, `http`, `mcp_tool` 유형에 대해 30초로, 대부분의 다른 이벤트에서 이 유형들의 기본값인 600초보다 짧습니다. 이 훅은 모든 프롬프트 전에 실행되고 완료될 때까지 모델 처리를 차단하므로, 멈춘 훅은 세션을 지연시킵니다. 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정합니다.
1418
1419[`async: true`](#run-hooks-in-the-background)로 실행하는 command 훅을 제외하면, 타임아웃에 도달한 `UserPromptSubmit` command, HTTP 또는 MCP 도구 훅은 취소되며 `additionalContext`를 포함한 출력이 버려집니다. 프롬프트는 해당 컨텍스트 없이 Claude에 전달됩니다. 트랜스크립트에는 훅 이름, 발생한 타임아웃, 출력이 버려졌다는 사실을 알리는 알림이 표시됩니다.
1420
1421타임아웃에 도달한 `UserPromptSubmit`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)은 훅 이름과 타임아웃을 명시한 메시지와 함께 프롬프트를 차단합니다. 해당 위치의 콜백은 실패 시 열림(fail open) 상태가 되어서는 안 되는 정책 게이트 역할을 할 수 있기 때문입니다. 세션은 계속됩니다. v2.1.208 이전에는 해당 이벤트에서 콜백 타임아웃이 발생하면 실행 오류와 함께 턴이 종료되었습니다.
1416 1422
1417<h4 id="userpromptsubmit-input">1423<h4 id="userpromptsubmit-input">
1418 UserPromptSubmit 입력1424 UserPromptSubmit 입력
1419</h4>1425</h4>
1420 1426
1421[공통 입력 필드](#common-input-fields) 외에도 UserPromptSubmit 훅은 사용자가 제출한 텍스트가 포함된 `prompt` 필드를 받습니다. `[Pasted text #N]` 자리 표시자로 축소된 붙여넣은 콘텐츠는 제자리에서 확장되어 도착합니다. Claude Code가 [Claude를 위해 붙여넣은 텍스트를 표시](/docs/ko/terminal-config#how-claude-treats-pasted-text)하는 세션에서는 확장된 콘텐츠가 `<pasted_content id="…">` 줄과 `</pasted_content id="…">` 줄 사이에 위치하므로, 훅이 프롬프트를 파싱한다면 이 줄들을 고려해야 합니다.1427[공통 입력 필드](#common-input-fields) 외에도 UserPromptSubmit 훅은 제출된 텍스트가 담긴 `prompt` 필드를 받습니다. `[Pasted text #N]` 자리 표시자로 축소된 붙여 넣은 콘텐츠는 제자리에 펼쳐진 상태로 전달됩니다. Claude Code가 [붙여 넣은 텍스트를 Claude용으로 표시하는](/docs/ko/terminal-config#how-claude-treats-pasted-text) 세션에서는 펼쳐진 콘텐츠가 `<pasted_content id="…">` 줄과 `</pasted_content id="…">` 줄 사이에 위치하므로, 훅이 프롬프트를 파싱한다면 해당 줄을 고려하세요.
1422 1428
1423UserPromptSubmit 훅은 세션에 사용자 지정 제목이 있으면 `session_title`도 받으며, 의미는 [SessionStart `session_title` 필드](#sessionstart-input)와 같습니다.1429UserPromptSubmit 훅은 세션에 사용자 지정 제목이 있을 때 `session_title`도 수신하며, 의미는 [SessionStart의 `session_title` 필드](#sessionstart-input)와 같습니다.
1424 1430
1425```json theme={null}1431```json theme={null}
1426{1432{
1437 UserPromptSubmit 결정 제어1443 UserPromptSubmit 결정 제어
1438</h4>1444</h4>
1439 1445
1440`UserPromptSubmit` 훅은 사용자 프롬프트의 처리 여부를 제어하고 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.1446`UserPromptSubmit` 훅은 제출된 프롬프트의 처리 여부를 제어하고 컨텍스트를 추가할 수 있습니다. 모든 [JSON 출력 필드](#json-output)를 사용할 수 있습니다.
1441 1447
1442종료 코드 0에서 대화에 컨텍스트를 추가하는 방법은 두 가지입니다.1448종료 코드 0에서 대화에 컨텍스트를 추가하는 방법은 두 가지입니다.
1443 1449
1444* **일반 텍스트 stdout**: Claude Code는 [일반 텍스트로 취급하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다1450* **일반 텍스트 stdout**: Claude Code는 [일반 텍스트로 처리하는](#exit-code-0) stdout을 Claude의 컨텍스트에 추가합니다
1445* **`additionalContext`가 있는 JSON**: 더 세밀하게 제어하려면 아래 JSON 형식을 사용합니다. `additionalContext` 필드가 컨텍스트로 추가됩니다1451* **`additionalContext`가 포함된 JSON**: 더 세밀하게 제어하려면 아래 JSON 형식을 사용합니다. `additionalContext` 필드가 컨텍스트로 추가됩니다
1446 1452
1447어느 채널도 트랜스크립트에 표시되는 항목을 생성하지 않습니다. 일반 stdout과 `additionalContext` 값은 각각 훅 이름으로 시작하는 시스템 리마인더로 주입되며, Claude는 둘 다 읽습니다. 전달을 확인하려면 [디버그 로그](#debug-hooks)를 확인합니다.1453어느 채널도 트랜스크립트에 보이는 항목을 생성하지 않습니다. 일반 stdout과 `additionalContext` 값은 각각 훅 이름으로 시작하는 시스템 리마인더로 주입되며, Claude는 둘 다 읽습니다. 전달 여부를 확인하려면 [디버그 로그](#debug-hooks)를 확인합니다.
1448 1454
1449프롬프트를 차단하려면 `decision`이 `"block"`으로 설정된 JSON 객체를 반환합니다.1455프롬프트를 차단하려면 `decision`이 `"block"`으로 설정된 JSON 객체를 반환합니다.
1450 1456
1451| 필드 | 설명 |1457| 필드 | 설명 |
1452| :- | :- |1458| :- | :- |
1453| `decision` | `"block"`은 프롬프트가 Claude에게 도달하기 전에 중지합니다. 프롬프트 진행을 허용하려면 생략합니다 |1459| `decision` | `"block"`은 프롬프트가 Claude에 도달하기 전에 중지합니다. 프롬프트 진행을 허용하려면 생략합니다 |
1454| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다. 컨텍스트에는 추가되지 않습니다 |1460| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다. 컨텍스트에는 추가되지 않습니다 |
1455| `additionalContext` | 제출된 프롬프트와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |1461| `additionalContext` | 제출된 프롬프트와 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
1456| `sessionTitle` | 세션 제목을 설정합니다. 프롬프트 내용을 기반으로 세션 이름을 자동 지정할 때 사용합니다 |1462| `sessionTitle` | 세션 제목을 설정합니다. 프롬프트 내용을 기반으로 세션 이름을 자동으로 지정하는 데 사용합니다 |
1457| `suppressOriginalPrompt` | 훅이 프롬프트를 차단할 때 `true`이면 차단 메시지에서 프롬프트 텍스트를 제외합니다. [차단된 프롬프트가 남기는 것](#what-a-blocked-prompt-leaves-behind)을 참조하십시오 |1463| `suppressOriginalPrompt` | 훅이 프롬프트를 차단할 때 `true`이면 차단 메시지에서 프롬프트 텍스트를 제외합니다. [차단된 프롬프트가 남기는 것](#what-a-blocked-prompt-leaves-behind)을 참조하세요 |
1458 1464
1459종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. 차단 메시지는 stderr 텍스트를 사용자에게 표시하며, 컨텍스트에는 추가되지 않습니다.1465종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. 차단 메시지에 stderr 텍스트가 사용자에게 표시되며, 컨텍스트에는 추가되지 않습니다.
1460 1466
1461```json theme={null}1467```json theme={null}
1462{1468{
1475 차단된 프롬프트가 남기는 것1481 차단된 프롬프트가 남기는 것
1476</h4>1482</h4>
1477 1483
1478차단된 프롬프트는 Claude에게 도달하지 않지만, 그 텍스트가 모든 곳에서 제거되는 것은 아닙니다. 기본적으로 사용자에게 표시되는 차단 메시지는 `Original prompt:` 뒤에 제출된 텍스트로 끝나며, Claude Code는 이 메시지를 디스크의 세션 트랜스크립트 파일에 씁니다. 메시지에서 텍스트를 제외하려면 `hookSpecificOutput` 안에 `"suppressOriginalPrompt": true`가 있는 JSON을 출력합니다. 이는 훅이 `decision: "block"`으로 차단하든 종료 코드 2로 차단하든 작동합니다. JSON을 출력하지 않는 종료 코드 2 훅은 항상 차단 메시지에 프롬프트 텍스트가 포함됩니다.1484차단된 프롬프트는 Claude에 도달하지 않지만, 그 텍스트가 모든 곳에서 제거되는 것은 아닙니다. 기본적으로 사용자에게 표시되는 차단 메시지는 `Original prompt:` 뒤에 제출된 텍스트가 오는 형태로 끝나며, Claude Code는 이 메시지를 디스크의 세션 트랜스크립트 파일에 기록합니다. 메시지에서 텍스트를 제외하려면 `hookSpecificOutput` 안에 `"suppressOriginalPrompt": true`가 포함된 JSON을 출력합니다. 이는 훅이 `decision: "block"`으로 차단하든 종료 코드 2로 차단하든 작동합니다. JSON을 출력하지 않는 종료 코드 2 훅은 항상 차단 메시지에 프롬프트 텍스트가 포함됩니다.
1479 1485
1480`suppressOriginalPrompt`는 차단 메시지만 변경합니다. 제출된 텍스트는 세션 트랜스크립트나 프롬프트 기록 같은 로컬 파일에 여전히 나타날 수 있으므로, 차단 훅은 비밀 정보를 디스크에 남기지 않는 방법이 아닙니다. 이러한 파일을 제한하거나 제거하려면 [일반 텍스트 스토리지](/docs/ko/claude-directory#plaintext-storage) 및 [로컬 데이터 지우기](/docs/ko/claude-directory#clear-local-data)를 참조하십시오.1486`suppressOriginalPrompt`는 차단 메시지만 변경합니다. 제출된 텍스트는 세션 트랜스크립트나 프롬프트 기록 같은 로컬 파일에 여전히 나타날 수 있으므로, 차단 훅은 비밀 정보를 디스크에 남기지 않는 방법이 아닙니다. 이러한 파일을 제한하거나 제거하려면 [일반 텍스트 스토리지](/docs/ko/claude-directory#plaintext-storage) 및 [로컬 데이터 지우기](/docs/ko/claude-directory#clear-local-data)를 참조하세요.
1481 1487
1482<h3 id="userpromptexpansion">1488<h3 id="userpromptexpansion">
1483 UserPromptExpansion1489 UserPromptExpansion
1484</h3>1490</h3>
1485 1491
1486사용자가 입력한 명령이 Claude에게 도달하기 전에 프롬프트로 확장될 때 실행됩니다. 특정 명령의 직접 호출을 차단하거나, 특정 스킬에 컨텍스트를 주입하거나, 사용자가 호출하는 명령을 로그에 기록하는 데 사용합니다. 예를 들어 `deploy`와 일치하는 훅은 승인 파일이 없으면 `/deploy`를 차단할 수 있고, 리뷰 스킬과 일치하는 훅은 팀의 리뷰 체크리스트를 `additionalContext`로 추가할 수 있습니다.1492사용자가 입력한 명령이 Claude에 도달하기 전에 프롬프트로 확장될 때 실행됩니다. 특정 명령의 직접 호출을 차단하거나, 특정 스킬에 컨텍스트를 주입하거나, 사용자가 호출하는 명령을 로그에 기록하는 데 사용합니다. 예를 들어 `deploy`와 일치하는 훅은 승인 파일이 없으면 `/deploy`를 차단할 수 있고, 리뷰 스킬과 일치하는 훅은 팀의 리뷰 체크리스트를 `additionalContext`로 추가할 수 있습니다.
1487 1493
1488이 이벤트는 `PreToolUse`가 다루지 않는 경로를 다룹니다. `Skill` 도구와 일치하는 `PreToolUse` 훅은 Claude가 도구를 호출할 때만 발생하지만, `/skillname`을 직접 입력하면 `PreToolUse`를 우회합니다. `UserPromptExpansion`은 이 직접 경로에서 발생합니다.1494이 이벤트는 `PreToolUse`가 다루지 않는 경로를 다룹니다. `Skill` 도구와 일치하는 `PreToolUse` 훅은 Claude가 도구를 호출할 때만 발생하지만, `/skillname`을 직접 입력하면 `PreToolUse`를 거치지 않습니다. `UserPromptExpansion`은 이 직접 경로에서 발생합니다.
1489 1495
1490`command_name`에 대해 일치시킵니다. 모든 프롬프트 유형 명령에서 발생시키려면 matcher를 비워 둡니다.1496`command_name`에 대해 일치시킵니다. 모든 프롬프트 유형 명령에서 발생시키려면 matcher를 비워 둡니다.
1491 1497
1493 UserPromptExpansion 입력1499 UserPromptExpansion 입력
1494</h4>1500</h4>
1495 1501
1496[공통 입력 필드](#common-input-fields) 외에도 UserPromptExpansion 훅은 `expansion_type`, `command_name`, `command_args`, `command_source`, 원본 `prompt` 문자열을 받습니다. `expansion_type` 필드는 스킬 및 사용자 지정 명령의 경우 `slash_command`, MCP 서버 프롬프트의 경우 `mcp_prompt`입니다.1502[공통 입력 필드](#common-input-fields) 외에도 UserPromptExpansion 훅은 `expansion_type`, `command_name`, `command_args`, `command_source`, 그리고 원래의 `prompt` 문자열을 수신합니다. `expansion_type` 필드는 스킬 및 사용자 지정 명령의 경우 `slash_command`, MCP 서버 프롬프트의 경우 `mcp_prompt`입니다.
1497 1503
1498```json theme={null}1504```json theme={null}
1499{1505{
1520| :- | :- |1526| :- | :- |
1521| `decision` | `"block"`은 명령이 확장되지 않도록 합니다. 진행을 허용하려면 생략합니다 |1527| `decision` | `"block"`은 명령이 확장되지 않도록 합니다. 진행을 허용하려면 생략합니다 |
1522| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다 |1528| `reason` | `decision`이 `"block"`일 때 사용자에게 표시됩니다 |
1523| `additionalContext` | 확장된 프롬프트와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |1529| `additionalContext` | 확장된 프롬프트와 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
1524 1530
1525종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. 차단 메시지는 stderr 텍스트를 사용자에게 표시합니다.1531종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. 차단 메시지에 stderr 텍스트가 사용자에게 표시됩니다.
1526 1532
1527```json theme={null}1533```json theme={null}
1528{1534{
1539 MessageDisplay1545 MessageDisplay
1540</h3>1546</h3>
1541 1547
1542어시스턴트 메시지가 화면에 스트리밍되는 동안 실행됩니다. Claude Code는 메시지를 단계적으로 표시합니다. 새로 완성된 줄의 배치가 렌더링될 준비가 될 때마다 훅이 해당 줄로 한 번 실행되고, Claude Code는 그 자리에 훅의 대체 텍스트를 렌더링합니다. 긴 메시지는 여러 번 호출되며, 짧은 메시지는 한 번만 호출될 수도 있습니다.1548어시스턴트 메시지가 화면에 스트리밍되는 동안 실행됩니다. Claude Code는 메시지를 단계적으로 표시합니다. 새로 완성된 줄의 묶음이 렌더링될 준비가 될 때마다 훅이 해당 줄로 한 번 실행되고, Claude Code는 그 자리에 훅의 대체 텍스트를 렌더링합니다. 긴 메시지는 여러 번의 호출을 생성하며, 짧은 메시지는 한 번만 생성할 수도 있습니다.
1543 1549
1544MessageDisplay는 다음 용도로 사용합니다.1550MessageDisplay는 다음 용도로 사용합니다.
1545 1551
1547* Agent SDK 애플리케이션이 사용자에게 보여 주는 텍스트 변환1553* Agent SDK 애플리케이션이 사용자에게 보여 주는 텍스트 변환
1548* Claude의 응답에서 API 키나 내부 호스트 이름 가리기1554* Claude의 응답에서 API 키나 내부 호스트 이름 가리기
1549 1555
1550Claude Code는 훅이 반환할 때까지 각 배치를 보류하므로 훅을 빠르게 유지해야 합니다. 훅이 실패하거나 시간 초과되면 Claude Code는 원본 텍스트를 표시합니다. 이 이벤트의 기본 타임아웃은 10초이며, 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정합니다.1556Claude Code는 훅이 반환될 때까지 각 묶음을 보류하므로 훅을 빠르게 유지해야 합니다. 훅이 실패하거나 시간 초과되면 Claude Code는 원래 텍스트를 표시합니다. 이 이벤트의 기본 타임아웃은 10초이며, 훅에 더 많은 시간이 필요하면 훅 항목에서 `timeout` 필드를 설정합니다.
1551 1557
1552MessageDisplay는 표시 전용입니다. 대체 텍스트는 화면에 렌더링되는 내용만 변경합니다. 트랜스크립트와 Claude가 보는 내용은 원본 텍스트를 유지하므로 Claude는 대체 텍스트를 보지 않으며, 상세 모드에서는 원본이 표시됩니다. 훅은 어시스턴트 메시지 텍스트만 받으므로 도구 결과와 사용자가 입력한 텍스트는 변경 없이 렌더링됩니다.1558MessageDisplay는 표시 전용입니다. 대체 텍스트는 화면에 렌더링되는 내용만 변경합니다. 트랜스크립트와 Claude가 보는 내용은 원래 텍스트를 유지하므로 Claude는 대체 텍스트를 보지 않으며, verbose 모드에서는 원래 텍스트가 표시됩니다. 훅은 어시스턴트 메시지 텍스트만 수신하므로 도구 결과와 사용자가 입력하는 텍스트는 변경 없이 렌더링됩니다.
1553 1559
1554MessageDisplay는 matcher를 지원하지 않으며, 텍스트를 스트리밍하는 모든 어시스턴트 메시지에서 발생합니다. 도구 호출만 있는 응답처럼 텍스트가 없는 메시지는 이 훅을 트리거하지 않습니다.1560MessageDisplay는 matcher를 지원하지 않으며 텍스트를 스트리밍하는 모든 어시스턴트 메시지에서 발생합니다. 도구 호출만 있는 응답처럼 텍스트가 없는 메시지는 이 이벤트를 트리거하지 않습니다.
1555 1561
1556Agent SDK 쿼리와 `claude -p`를 포함한 비대화형 실행에서는 MessageDisplay가 줄 배치마다 한 번이 아니라 어시스턴트 메시지마다 한 번 실행됩니다. 단일 호출은 메시지가 완료된 후 도착하며 전체 메시지 텍스트를 전달합니다. `index`는 `0`, `final`은 `true`이고, `delta`에는 메시지 전체가 담깁니다. 각 메시지의 `delta` 텍스트를 수집하는 훅은 두 모드에서 동일한 전체 텍스트를 받습니다.1562Agent SDK 쿼리와 `claude -p`를 포함한 비대화형 실행에서는 MessageDisplay가 줄 묶음마다가 아니라 어시스턴트 메시지마다 한 번 실행됩니다. 단일 호출은 메시지가 완료된 후 도착하며 전체 메시지 텍스트를 담습니다. `index`는 `0`, `final`은 `true`이고, `delta`에는 전체 메시지가 들어 있습니다. 각 메시지의 `delta` 텍스트를 수집하는 훅은 두 모드에서 동일한 전체 텍스트를 수신합니다.
1557 1563
1558<h4 id="messagedisplay-input">1564<h4 id="messagedisplay-input">
1559 MessageDisplay 입력1565 MessageDisplay 입력
1560</h4>1566</h4>
1561 1567
1562[공통 입력 필드](#common-input-fields) 외에도 MessageDisplay 훅은 턴과 메시지의 식별자, 메시지 내에서 이 호출의 위치, `delta`의 새 텍스트를 받습니다. 배치 경계는 텍스트가 스트리밍되는 방식에 따라 달라지므로, 줄이 특정 방식으로 그룹화될 것으로 기대하지 말고 `index`와 `final`을 사용하여 메시지 진행 상황을 추적합니다.1568[공통 입력 필드](#common-input-fields) 외에도 MessageDisplay 훅은 턴과 메시지의 식별자, 메시지 내에서 이 호출의 위치, 그리고 `delta`의 새 텍스트를 수신합니다. 묶음 경계는 텍스트가 스트리밍되는 방식에 따라 달라지므로, 줄이 특정 방식으로 묶일 것이라고 기대하기보다 `index`와 `final`을 사용하여 메시지의 진행 상황을 추적합니다.
1563 1569
1564| 필드 | 설명 |1570| 필드 | 설명 |
1565| :- | :- |1571| :- | :- |
1566| `turn_id` | 현재 턴의 UUID |1572| `turn_id` | 현재 턴의 UUID |
1567| `message_id` | 표시 중인 어시스턴트 메시지의 UUID입니다. 같은 메시지의 모든 배치에서 동일하게 유지됩니다. API의 `msg_…` id가 아니므로 트랜스크립트 메시지 id와 연관시킬 수 없습니다 |1573| `message_id` | 표시 중인 어시스턴트 메시지의 UUID. 같은 메시지의 모든 묶음에서 동일하게 유지됩니다. API의 `msg_…` id가 아니므로 트랜스크립트 메시지 id와 연관시킬 수 없습니다 |
1568| `index` | 메시지 내에서 이 배치의 0부터 시작하는 인덱스 |1574| `index` | 메시지 내에서 이 묶음의 0부터 시작하는 인덱스 |
1569| `final` | 메시지의 마지막 배치에서 `true`입니다. 각 메시지에는 정확히 하나의 마지막 배치가 있습니다 |1575| `final` | 메시지의 마지막 묶음에서 `true`. 각 메시지에는 정확히 하나의 마지막 묶음이 있습니다 |
1570| `delta` | 이전 배치 이후 새로 완성된 줄이며, 끝의 줄바꿈이 포함됩니다. 줄 중간에서 끝날 수 있는 마지막 배치를 제외하면 항상 완전한 줄입니다. 대화형 실행에서 메시지가 줄바꿈으로 끝나면 마지막 배치의 delta는 비어 있으므로, 비어 있지 않은 delta가 아니라 `final`을 메시지 종료 신호로 취급해야 합니다. Agent SDK 및 `claude -p` 실행에서는 단일 호출이 메시지 전체를 전달합니다 |1576| `delta` | 이전 묶음 이후 새로 완성된 줄(끝의 줄바꿈 포함). 줄 중간에서 끝날 수 있는 마지막 묶음을 제외하면 항상 완전한 줄입니다. 대화형 실행에서는 메시지가 줄바꿈으로 끝나면 마지막 묶음의 delta가 비어 있으므로, 비어 있지 않은 delta가 아니라 `final`을 메시지 끝 신호로 취급해야 합니다. Agent SDK 및 `claude -p` 실행에서는 단일 호출이 전체 메시지를 담습니다 |
1571 1577
1572```json theme={null}1578```json theme={null}
1573{1579{
1587 MessageDisplay 출력1593 MessageDisplay 출력
1588</h4>1594</h4>
1589 1595
1590모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 MessageDisplay 훅은 화면의 delta를 대체하는 `displayContent`를 반환할 수 있습니다.1596모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 MessageDisplay 훅은 화면에서 delta를 대체하는 `displayContent`를 반환할 수 있습니다.
1591 1597
1592| 필드 | 설명 |1598| 필드 | 설명 |
1593| :- | :- |1599| :- | :- |
1594| `displayContent` | delta 대신 표시되는 텍스트입니다. 원본을 표시하려면 생략합니다 |1600| `displayContent` | delta 대신 표시되는 텍스트. 원래 텍스트를 표시하려면 생략합니다 |
1595 1601
1596MessageDisplay 훅에는 결정 제어가 없습니다. 메시지를 차단하거나 트랜스크립트에 저장되거나 Claude에게 전송되는 내용을 변경할 수 없습니다. Claude Code는 JSON 출력의 `displayContent`에 따라 동작하고 `systemMessage`와 `continue`는 버립니다.1602MessageDisplay 훅에는 결정 제어가 없습니다. 메시지를 차단하거나 트랜스크립트에 저장되는 내용 또는 Claude에 전송되는 내용을 변경할 수 없습니다. Claude Code는 JSON 출력의 `displayContent`에 따라 동작하며 `systemMessage`와 `continue`는 버립니다.
1597 1603
1598다음 예시는 일반 텍스트 표시를 위해 Claude의 응답에서 markdown 서식을 제거합니다. 스크립트는 stdin에서 각 배치를 읽고, `delta`에서 굵게 표시 기호와 인라인 코드 백틱을 제거한 다음, 결과를 `displayContent`로 반환합니다.1604다음 예시는 일반 텍스트 표시를 위해 Claude의 응답에서 markdown 서식을 제거합니다. 스크립트는 stdin에서 각 묶음을 읽고, `delta`에서 굵게 표시 기호와 인라인 코드 백틱을 제거한 다음, 결과를 `displayContent`로 반환합니다.
1599 1605
1600<Tabs>1606<Tabs>
1601 <Tab title="macOS/Linux">1607 <Tab title="macOS/Linux">
1602 설정 파일에서 이벤트에 대한 명령 훅을 등록합니다.1608 설정 파일에서 이벤트에 대한 command 훅을 등록합니다.
1603 1609
1604 ```json theme={null}1610 ```json theme={null}
1605 {1611 {
1628 </Tab>1634 </Tab>
1629 1635
1630 <Tab title="Windows (PowerShell)">1636 <Tab title="Windows (PowerShell)">
1631 PowerShell을 통해 스크립트를 실행하는 명령 훅을 등록합니다.1637 PowerShell을 통해 스크립트를 실행하는 command 훅을 등록합니다.
1632 1638
1633 ```json theme={null}1639 ```json theme={null}
1634 {1640 {
1654 }1660 }
1655 ```1661 ```
1656 1662
1657 `-NoProfile` 플래그는 PowerShell 프로필 로드를 건너뛰어 훅이 빠르게 시작되도록 하고, `-ExecutionPolicy Bypass`는 PowerShell이 로컬 스크립트 파일을 실행할 수 있게 합니다.1663 `-NoProfile` 플래그는 PowerShell 프로필 로드를 건너뛰어 훅이 빠르게 시작되도록 하며, `-ExecutionPolicy Bypass`는 PowerShell이 로컬 스크립트 파일을 실행할 수 있도록 합니다.
1658 1664
1659 이 스크립트를 프로젝트의 `.claude/hooks/plain-display.ps1`에 저장합니다.1665 이 스크립트를 프로젝트의 `.claude/hooks/plain-display.ps1`에 저장합니다.
1660 1666
1671 </Tab>1677 </Tab>
1672</Tabs>1678</Tabs>
1673 1679
1674markdown이 없는 배치는 변경 없이 통과합니다. 예를 들어 `jq`가 없어 스크립트가 실패하면, Claude Code는 원본 텍스트를 표시하고 실패 사실은 세션이 아닌 [디버그 출력](#debug-hooks)에만 기록합니다.1680markdown이 없는 묶음은 변경 없이 통과합니다. 예를 들어 `jq`가 없어서 스크립트가 실패하면 Claude Code는 원래 텍스트를 표시하며, 실패는 세션이 아닌 [디버그 출력](#debug-hooks)에만 기록됩니다.
1675 1681
1676<h3 id="pretooluse">1682<h3 id="pretooluse">
1677 PreToolUse1683 PreToolUse
1679 1685
1680Claude가 도구 매개변수를 생성한 후, 도구 호출을 처리하기 전에 실행됩니다. `EndConversation`을 제외한 모든 도구 이름에 대해 일치시킵니다. 여기에는 `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode` 같은 기본 제공 도구와 모든 [MCP 도구 이름](#match-mcp-tools)이 포함됩니다.1686Claude가 도구 매개변수를 생성한 후, 도구 호출을 처리하기 전에 실행됩니다. `EndConversation`을 제외한 모든 도구 이름에 대해 일치시킵니다. 여기에는 `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode` 같은 기본 제공 도구와 모든 [MCP 도구 이름](#match-mcp-tools)이 포함됩니다.
1681 1687
1682무엇이 파일을 썼든 디스크에서 특정 파일이 변경될 때 훅을 실행하려면, 파일 편집 도구를 이름으로 일치시키는 대신 [FileChanged](#filechanged)를 사용합니다. PreToolUse와 달리 Claude Code는 변경 후에 FileChanged 훅을 실행하며, 이 훅에는 결정 제어가 없으므로 쓰기를 차단할 수 없습니다.1688무엇이 작성했든 특정 파일이 디스크에서 변경될 때 훅을 실행하려면, 파일 편집 도구를 이름으로 일치시키는 대신 [FileChanged](#filechanged)를 사용합니다. PreToolUse와 달리 Claude Code는 변경 후에 FileChanged 훅을 실행하며, 이 훅에는 결정 제어가 없으므로 쓰기를 차단할 수 없습니다.
1683 1689
1684<Warning>1690<Warning>
1685 PreToolUse는 Claude가 도구를 호출할 때만 실행됩니다. [프롬프트에서 `@`로 참조한](/docs/ko/common-workflows#reference-files-and-directories) 파일은 도구 호출 없이 추가됩니다. Claude Code가 프롬프트를 구성하는 동안 파일 내용을 삽입하므로, `Read`와 일치하는 훅을 포함하여 어떤 PreToolUse 훅도 발생하지 않습니다. `@` 참조에서 특정 경로를 차단하려면 대신 [`Read` 거부 규칙](/docs/ko/permissions#read-and-edit)을 사용합니다.1691 PreToolUse는 Claude가 도구를 호출할 때만 실행됩니다. [프롬프트에서 `@`로 참조하는](/docs/ko/common-workflows#reference-files-and-directories) 파일은 도구 호출 없이 추가됩니다. Claude Code는 프롬프트를 구성하면서 파일 내용을 삽입하므로, `Read`와 일치하는 훅을 포함하여 어떤 PreToolUse 훅도 이 파일에 대해 발생하지 않습니다. `@` 참조에서 특정 경로를 차단하려면 대신 [`Read` 거부 규칙](/docs/ko/permissions#read-and-edit)을 사용합니다.
1686 1692
1687 PreToolUse는 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에서도 발생하지 않습니다.1693 PreToolUse는 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에서도 발생하지 않습니다.
1688</Warning>1694</Warning>
1689 1695
1690도구 호출을 허용, 거부, 확인 요청 또는 지연하려면 [PreToolUse 결정 제어](#pretooluse-decision-control)를 사용합니다.1696도구 호출을 허용, 거부, 확인 요청 또는 지연하려면 [PreToolUse 결정 제어](#pretooluse-decision-control)를 사용합니다.
1691 1697
1692`PreToolUse`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)이 타임아웃을 초과하면 도구 호출이 차단되고, Claude는 타임아웃을 명시한 오류 결과를 받습니다. 다른 훅이 반환한 명시적 거부는 여전히 우선합니다.1698타임아웃을 초과한 `PreToolUse`의 [Agent SDK 콜백 훅](/docs/ko/agent-sdk/hooks)은 도구 호출을 차단하며, Claude는 타임아웃을 명시한 오류 결과를 수신합니다. 다른 훅이 반환한 명시적 거부는 여전히 우선합니다.
1693 1699
1694<h4 id="pretooluse-input">1700<h4 id="pretooluse-input">
1695 PreToolUse 입력1701 PreToolUse 입력
1696</h4>1702</h4>
1697 1703
1698[공통 입력 필드](#common-input-fields) 외에도 PreToolUse 훅은 `tool_name`, `tool_input`, `tool_use_id`를 받습니다.1704[공통 입력 필드](#common-input-fields) 외에도 PreToolUse 훅은 `tool_name`, `tool_input`, `tool_use_id`를 수신합니다.
1699 1705
1700[MCP 도구](#match-mcp-tools)의 경우 입력에 `mcp_server`도 포함됩니다. 이는 서버의 `name`과 서버 정의의 출처를 나타내는 `source`를 가진 객체입니다. `source` 값에는 `plugin`, `sdk`, 그리고 `user`, `project` 같은 구성 범위가 포함됩니다. Agent SDK 참조의 [`McpServerProvenance`](/docs/ko/agent-sdk/typescript#mcpserverprovenance)에 모든 값이 나열되어 있으며, 인식하지 못하는 값을 처리하는 방법도 설명되어 있습니다. 신뢰 결정은 `name`이나 `mcp__<server>__` 도구 이름 접두사가 아닌 `source`를 기반으로 내려야 합니다. `mcp_server` 필드를 사용하려면 Claude Code v2.1.274 이상이 필요합니다.1706[MCP 도구](#match-mcp-tools)의 경우 입력에는 `mcp_server`도 포함됩니다. 이는 서버의 `name`과 서버 정의의 출처를 나타내는 `source`가 담긴 객체입니다. `source` 값에는 `plugin`, `sdk`, 그리고 `user`, `project` 같은 구성 범위가 포함됩니다. Agent SDK 레퍼런스의 [`McpServerProvenance`](/docs/ko/agent-sdk/typescript#mcpserverprovenance)에서 전체 값 목록과 인식하지 못하는 값을 처리하는 방법을 확인할 수 있습니다. 신뢰 결정은 `name`이나 `mcp__<server>__` 도구 이름 접두사가 아닌 `source`를 기준으로 내려야 합니다. `mcp_server` 필드에는 Claude Code v2.1.274 이상이 필요합니다.
1701 1707
1702파일 도구 `Write`, `Edit`, `Read`의 경우 `tool_input.file_path`는 항상 절대 경로입니다.1708파일 도구 `Write`, `Edit`, `Read`의 경우 `tool_input.file_path`는 항상 절대 경로입니다.
1703 1709
1704* Claude Code는 훅이 실행되기 전에 `~`와 상대 경로를 확장하므로, 경로에 대해 일치시키는 훅은 `~`나 같은 경로의 상대 표기로 우회할 수 없습니다1710* Claude Code는 훅이 실행되기 전에 `~`와 상대 경로를 확장하므로, 경로를 일치시키는 훅은 `~`나 같은 경로의 상대 표기를 통해 우회될 수 없습니다
1705* Windows에서는 훅이 `$PWD`가 `/c/project`처럼 보이는 Git Bash에서 실행되더라도 경로가 백슬래시 구분 기호로 도착합니다1711* Windows에서는 훅이 `$PWD`가 `/c/project`처럼 보이는 Git Bash에서 실행되더라도 경로가 백슬래시 구분 기호와 함께 전달됩니다
1706* `/src/` 검사처럼 슬래시로 작성된 비교는 백슬래시 경로와 절대 일치하지 않으며, 도구 호출은 훅이 차단할 것이 없었던 것처럼 진행됩니다1712* `/src/` 검사처럼 슬래시로 작성된 비교는 백슬래시 경로와 절대 일치하지 않으며, 도구 호출은 훅이 차단할 것이 없는 것처럼 진행됩니다
1707* 비교하기 전에 구분 기호를 정규화합니다. Bash에서는 `FILE_PATH="${FILE_PATH//\\//}"`, Python에서는 `file_path.replace("\\", "/")`를 사용한 다음, 경로가 절대 경로이므로 `^`로 고정하지 말고 `/src/` 같은 경로 세그먼트와 일치시킵니다1713* 비교하기 전에 구분 기호를 정규화합니다. Bash에서는 `FILE_PATH="${FILE_PATH//\\//}"`, Python에서는 `file_path.replace("\\", "/")`를 사용한 다음, 경로가 절대 경로이므로 `^`로 고정하지 말고 `/src/` 같은 경로 세그먼트를 일치시킵니다
1708 1714
1709Windows에서 `Write` 호출은 다음을 전달합니다.1715Windows에서 `Write` 호출은 다음을 전달합니다.
1710 1716
1730 1736
1731셸 명령을 실행합니다.1737셸 명령을 실행합니다.
1732 1738
1733| 필드 | 유형 | 예시 | 설명 |1739| 필드 | 타입 | 예시 | 설명 |
1734| :- | :- | :- | :- |1740| :- | :- | :- | :- |
1735| `command` | string | `"npm test"` | 실행할 셸 명령 |1741| `command` | string | `"npm test"` | 실행할 셸 명령 |
1736| `description` | string | `"Run test suite"` | 명령이 수행하는 작업에 대한 선택적 설명 |1742| `description` | string | `"Run test suite"` | 명령이 수행하는 작업에 대한 선택적 설명 |
1737| `timeout` | number | `120000` | 밀리초 단위의 선택적 타임아웃입니다. [최대값](/docs/ko/tools-reference#bash-tool-behavior)을 초과하는 값은 거부되지 않고 최대값으로 줄어듭니다 |1743| `timeout` | number | `120000` | 선택적 타임아웃(밀리초). [최대값](/docs/ko/tools-reference#bash-tool-behavior)을 초과하는 값은 거부되지 않고 최대값으로 줄어듭니다 |
1738| `run_in_background` | boolean | `false` | 명령을 백그라운드에서 실행할지 여부 |1744| `run_in_background` | boolean | `false` | 명령을 백그라운드에서 실행할지 여부 |
1739 1745
1740Bash 명령이 Git 저장소의 파일을 변경하면 Claude Code는 변경된 내용을 기록할 수 있습니다. [`bashEditDiffEnabled`](/docs/ko/settings-reference#basheditdiffenabled) 설정으로 기록을 켜면 모든 권한 모드에서 변경 사항을 기록하며, 어떤 파일에서 이 설정을 지정할 수 있는지는 해당 설정 항목에 설명되어 있습니다. 그렇지 않으면 자동 모드와 `bypassPermissions` 모드에서만, 그리고 Claude Code가 Claude에게 Bash를 통해 파일을 편집하도록 지시할 때만 기록합니다. 기록을 끄려면 `bashEditDiffEnabled`를 `false`로 설정합니다. 백그라운드 명령과 읽기 전용 명령에는 diff가 없습니다.1746Bash 명령이 Git 저장소의 파일을 변경하면 Claude Code는 변경된 내용을 기록할 수 있습니다. [`bashEditDiffEnabled`](/docs/ko/settings-reference#basheditdiffenabled) 설정이 기록을 켜면 모든 권한 모드에서 변경 사항을 기록하며, 어떤 파일에서 이 설정을 지정할 수 있는지는 해당 설정 항목에 나와 있습니다. 그렇지 않으면 자동 모드와 `bypassPermissions` 모드에서만, 그리고 Claude Code가 Claude에게 Bash를 통해 파일을 편집하도록 지시한 경우에만 기록합니다. 기록을 끄려면 `bashEditDiffEnabled`를 `false`로 설정합니다. 백그라운드 명령과 읽기 전용 명령에는 diff가 포함되지 않습니다.
1741 1747
1742그러면 [PostToolUse 훅](#posttooluse)은 `tool_response.bashEditDiff`에서 변경된 파일을 받습니다. 이 목록은 명령이 실행되는 동안 저장소 아래에서 변경된 내용을 다룹니다. Git이 무시하는 파일과 서브모듈의 파일은 나열되지 않습니다. Claude Code v2.1.269 이상이 필요합니다.1748그러면 [PostToolUse 훅](#posttooluse)이 `tool_response.bashEditDiff`에서 변경된 파일을 수신합니다. 이 목록은 명령이 실행되는 동안 저장소 아래에서 변경된 내용을 다룹니다. Git이 무시하는 파일과 서브모듈의 파일은 목록에 포함되지 않습니다. Claude Code v2.1.269 이상이 필요합니다.
1743 1749
1744<Note>1750<Note>
1745 이 목록은 최선의 노력에 기반한 것이며 공개 베타 상태입니다. Claude Code는 변경 사항을 놓치거나, 다른 프로세스가 동시에 변경한 파일을 포함하거나, 크기 제한에서 중단될 수 있습니다. 필드 형태는 변경될 수 있습니다. 이 목록은 정책을 강제하는 용도가 아니라 검토할 대상을 찾는 용도로 사용합니다.1751 이 목록은 최선의 노력(best effort)으로 제공되며 공개 베타 상태입니다. Claude Code는 변경 사항을 놓치거나, 동시에 다른 프로세스가 변경한 파일을 포함하거나, 크기 제한에서 중단될 수 있습니다. 필드 형태는 변경될 수 있습니다. 이 목록은 정책을 강제하는 용도가 아니라 검토할 대상을 찾는 용도로 사용합니다.
1746</Note>1752</Note>
1747 1753
1748`changedFiles`와 `files`는 명령이 변경한 내용을 나열하며, 나머지 필드는 해당 목록이 얼마나 완전하고 신뢰할 수 있는지를 나타냅니다.1754`changedFiles`와 `files`는 명령이 변경한 내용을 나열하며, 나머지 필드는 해당 목록이 얼마나 완전하고 신뢰할 수 있는지를 나타냅니다.
1749 1755
1750| 필드 | 유형 | 예시 | 설명 |1756| 필드 | 타입 | 예시 | 설명 |
1751| :- | :- | :- | :- |1757| :- | :- | :- | :- |
1752| `changedFiles` | array | `["/path/to/src/app.ts"]` | 명령이 변경한 파일의 절대 경로이며, 최대 200개입니다. `files`에 diff가 있거나 `moreFiles`가 0보다 클 때마다 존재합니다 |1758| `changedFiles` | array | `["/path/to/src/app.ts"]` | 명령이 변경한 파일의 절대 경로(최대 200개). `files`에 diff가 있거나 `moreFiles`가 0보다 클 때마다 포함됩니다 |
1753| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 표시용으로 최대 5개의 변경된 파일 diff입니다. 명령이 추가하거나 제거한 파일에는 `created` 또는 `deleted`가 `true`입니다 |1759| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 표시용으로 최대 5개의 변경된 파일에 대한 diff. 명령이 추가하거나 제거한 파일의 경우 `created` 또는 `deleted`가 `true`입니다 |
1754| `moreFiles` | number | `2` | `files`에 diff가 없는 변경된 파일 수 |1760| `moreFiles` | number | `2` | `files`에 diff가 없는 변경된 파일 수 |
1755| `unavailable` | boolean | `true` | diff가 불완전하거나 가져올 수 없을 때 설정됩니다 |1761| `unavailable` | boolean | `true` | diff가 불완전하거나 가져올 수 없을 때 설정됩니다 |
1756| `skipped` | boolean | `true` | `git checkout`이나 `git stash`처럼 작업 트리를 이동하는 Git 명령에 설정되며, 이 경우 Claude Code는 diff를 가져오지 않습니다 |1762| `skipped` | boolean | `true` | `git checkout`이나 `git stash`처럼 작업 트리를 이동하는 Git 명령에 대해 설정되며, 이 경우 Claude Code는 diff를 가져오지 않습니다 |
1757| `shared` | boolean | `true` | 서브에이전트의 호출 같은 다른 Bash 도구 호출이 같은 저장소에서 동시에 실행되었을 때 설정되며, 이 경우 나열된 일부 변경 사항은 해당 명령의 것일 수 있습니다 |1763| `shared` | boolean | `true` | 서브에이전트의 호출 같은 다른 Bash 도구 호출이 같은 시간에 같은 저장소에서 실행되어, 나열된 일부 변경 사항이 해당 명령의 것일 수 있을 때 설정됩니다 |
1758 1764
1759<a id="powershell" />1765<a id="powershell" />
1760 1766
1762 PowerShell1768 PowerShell
1763</h5>1769</h5>
1764 1770
1765PowerShell 명령을 실행합니다. 플랫폼별 사용 가능 여부는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 참조하십시오.1771PowerShell 명령을 실행합니다. 플랫폼별 사용 가능 여부는 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 참조하세요.
1766 1772
1767필드는 Bash 도구와 같으며, 명령 문자열은 `command`에 있습니다.1773필드는 Bash 도구와 같으며, 명령 문자열은 `command`에 들어갑니다.
1768 1774
1769| 필드 | 유형 | 예시 | 설명 |1775| 필드 | 타입 | 예시 | 설명 |
1770| :- | :- | :- | :- |1776| :- | :- | :- | :- |
1771| `command` | string | `"Get-ChildItem -Recurse"` | 실행할 PowerShell 명령 |1777| `command` | string | `"Get-ChildItem -Recurse"` | 실행할 PowerShell 명령 |
1772| `description` | string | `"List files recursively"` | 명령이 수행하는 작업에 대한 선택적 설명 |1778| `description` | string | `"List files recursively"` | 명령이 수행하는 작업에 대한 선택적 설명 |
1773| `timeout` | number | `120000` | 밀리초 단위의 선택적 타임아웃 |1779| `timeout` | number | `120000` | 선택적 타임아웃(밀리초) |
1774| `run_in_background` | boolean | `false` | 명령을 백그라운드에서 실행할지 여부 |1780| `run_in_background` | boolean | `false` | 명령을 백그라운드에서 실행할지 여부 |
1775 1781
1776셸 명령을 검사하는 훅에서는 두 도구를 모두 다루도록 `Bash|PowerShell`과 일치시킵니다.1782셸 명령을 검사하는 훅에서는 두 도구를 모두 다루도록 `Bash|PowerShell`을 일치시킵니다.
1777 1783
1778* Windows에서 PowerShell 도구가 활성화된 곳이라면 Claude는 PowerShell을 기본 셸로 취급하고 셸 명령을 PowerShell을 통해 전달합니다.1784* Windows에서 PowerShell 도구가 활성화된 곳이라면 어디서든 Claude는 PowerShell을 기본 셸로 취급하고 셸 명령을 PowerShell을 통해 라우팅합니다.
1779* Git Bash가 없는 Windows에서는 이 도구가 자동으로 활성화되며 Claude Code는 Bash 도구를 아예 등록하지 않습니다.1785* Git Bash가 없는 Windows에서는 이 도구가 자동으로 활성화되며 Claude Code는 Bash 도구를 전혀 등록하지 않습니다.
1780* `Bash`만 일치시키는 훅은 그런 환경에서 절대 발생하지 않습니다.1786* `Bash`만 일치시키는 훅은 그곳에서 절대 발생하지 않습니다.
1781 1787
1782<h5 id="write">1788<h5 id="write">
1783 Write1789 Write
1785 1791
1786파일을 생성하거나 덮어씁니다.1792파일을 생성하거나 덮어씁니다.
1787 1793
1788| 필드 | 유형 | 예시 | 설명 |1794| 필드 | 타입 | 예시 | 설명 |
1789| :- | :- | :- | :- |1795| :- | :- | :- | :- |
1790| `file_path` | string | `"/path/to/file.txt"` | 쓸 파일의 절대 경로 |1796| `file_path` | string | `"/path/to/file.txt"` | 쓸 파일의 절대 경로 |
1791| `content` | string | `"file content"` | 파일에 쓸 내용 |1797| `content` | string | `"file content"` | 파일에 쓸 내용 |
1794 Edit1800 Edit
1795</h5>1801</h5>
1796 1802
1797기존 파일의 문자열을 바꿉니다.1803기존 파일의 문자열을 대체합니다.
1798 1804
1799| 필드 | 유형 | 예시 | 설명 |1805| 필드 | 타입 | 예시 | 설명 |
1800| :- | :- | :- | :- |1806| :- | :- | :- | :- |
1801| `file_path` | string | `"/path/to/file.txt"` | 편집할 파일의 절대 경로 |1807| `file_path` | string | `"/path/to/file.txt"` | 편집할 파일의 절대 경로 |
1802| `old_string` | string | `"original text"` | 찾아서 바꿀 텍스트 |1808| `old_string` | string | `"original text"` | 찾아서 대체할 텍스트 |
1803| `new_string` | string | `"replacement text"` | 대체 텍스트 |1809| `new_string` | string | `"replacement text"` | 대체 텍스트 |
1804| `replace_all` | boolean | `false` | 모든 항목을 바꿀지 여부 |1810| `replace_all` | boolean | `false` | 모든 항목을 대체할지 여부 |
1805 1811
1806<h5 id="read">1812<h5 id="read">
1807 Read1813 Read
1809 1815
1810파일 내용을 읽습니다.1816파일 내용을 읽습니다.
1811 1817
1812| 필드 | 유형 | 예시 | 설명 |1818| 필드 | 타입 | 예시 | 설명 |
1813| :- | :- | :- | :- |1819| :- | :- | :- | :- |
1814| `file_path` | string | `"/path/to/file.txt"` | 읽을 파일의 절대 경로 |1820| `file_path` | string | `"/path/to/file.txt"` | 읽을 파일의 절대 경로 |
1815| `offset` | number | `10` | 읽기를 시작할 선택적 줄 번호 |1821| `offset` | number | `10` | 읽기를 시작할 선택적 줄 번호 |
1821 1827
1822glob 패턴과 일치하는 파일을 찾습니다.1828glob 패턴과 일치하는 파일을 찾습니다.
1823 1829
1824| 필드 | 유형 | 예시 | 설명 |1830| 필드 | 타입 | 예시 | 설명 |
1825| :- | :- | :- | :- |1831| :- | :- | :- | :- |
1826| `pattern` | string | `"**/*.ts"` | 파일과 일치시킬 glob 패턴 |1832| `pattern` | string | `"**/*.ts"` | 파일을 일치시킬 glob 패턴 |
1827| `path` | string | `"/path/to/dir"` | 검색할 선택적 디렉터리입니다. 기본값은 현재 작업 디렉터리입니다 |1833| `path` | string | `"/path/to/dir"` | 검색할 선택적 디렉터리. 기본값은 현재 작업 디렉터리입니다 |
1828 1834
1829<h5 id="grep">1835<h5 id="grep">
1830 Grep1836 Grep
1832 1838
1833정규식으로 파일 내용을 검색합니다.1839정규식으로 파일 내용을 검색합니다.
1834 1840
1835| 필드 | 유형 | 예시 | 설명 |1841| 필드 | 타입 | 예시 | 설명 |
1836| :- | :- | :- | :- |1842| :- | :- | :- | :- |
1837| `pattern` | string | `"TODO.*fix"` | 검색할 정규식 패턴 |1843| `pattern` | string | `"TODO.*fix"` | 검색할 정규식 패턴 |
1838| `path` | string | `"/path/to/dir"` | 검색할 선택적 파일 또는 디렉터리 |1844| `path` | string | `"/path/to/dir"` | 검색할 선택적 파일 또는 디렉터리 |
1839| `glob` | string | `"*.ts"` | 파일을 필터링할 선택적 glob 패턴 |1845| `glob` | string | `"*.ts"` | 파일을 필터링할 선택적 glob 패턴 |
1840| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` 또는 `"count"`. 기본값은 `"files_with_matches"`입니다 |1846| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` 또는 `"count"`. 기본값은 `"files_with_matches"`입니다 |
1841| `-i` | boolean | `true` | 대소문자를 구분하지 않는 검색 |1847| `-i` | boolean | `true` | 대소문자 구분 없는 검색 |
1842| `multiline` | boolean | `false` | 여러 줄 일치 활성화 |1848| `multiline` | boolean | `false` | 여러 줄 일치 활성화 |
1843 1849
1844<h5 id="webfetch">1850<h5 id="webfetch">
1847 1853
1848웹 콘텐츠를 가져와 처리합니다.1854웹 콘텐츠를 가져와 처리합니다.
1849 1855
1850| 필드 | 유형 | 예시 | 설명 |1856| 필드 | 타입 | 예시 | 설명 |
1851| :- | :- | :- | :- |1857| :- | :- | :- | :- |
1852| `url` | string | `"https://example.com/api"` | 콘텐츠를 가져올 URL |1858| `url` | string | `"https://example.com/api"` | 콘텐츠를 가져올 URL |
1853| `prompt` | string | `"Extract the API endpoints"` | 가져온 콘텐츠에 실행할 프롬프트 |1859| `prompt` | string | `"Extract the API endpoints"` | 가져온 콘텐츠에 대해 실행할 프롬프트 |
1854 1860
1855<h5 id="websearch">1861<h5 id="websearch">
1856 WebSearch1862 WebSearch
1858 1864
1859웹을 검색합니다.1865웹을 검색합니다.
1860 1866
1861| 필드 | 유형 | 예시 | 설명 |1867| 필드 | 타입 | 예시 | 설명 |
1862| :- | :- | :- | :- |1868| :- | :- | :- | :- |
1863| `query` | string | `"react hooks best practices"` | 검색 쿼리 |1869| `query` | string | `"react hooks best practices"` | 검색 쿼리 |
1864| `allowed_domains` | array | `["docs.example.com"]` | 선택 사항: 이 도메인의 결과만 포함합니다 |1870| `allowed_domains` | array | `["docs.example.com"]` | 선택 사항: 이 도메인의 결과만 포함 |
1865| `blocked_domains` | array | `["spam.example.com"]` | 선택 사항: 이 도메인의 결과를 제외합니다 |1871| `blocked_domains` | array | `["spam.example.com"]` | 선택 사항: 이 도메인의 결과 제외 |
1866 1872
1867<h5 id="agent">1873<h5 id="agent">
1868 Agent1874 Agent
1870 1876
1871[서브에이전트](/docs/ko/sub-agents)를 생성합니다.1877[서브에이전트](/docs/ko/sub-agents)를 생성합니다.
1872 1878
1873| 필드 | 유형 | 예시 | 설명 |1879| 필드 | 타입 | 예시 | 설명 |
1874| :- | :- | :- | :- |1880| :- | :- | :- | :- |
1875| `prompt` | string | `"Find all API endpoints"` | 에이전트가 수행할 작업 |1881| `prompt` | string | `"Find all API endpoints"` | 에이전트가 수행할 작업 |
1876| `description` | string | `"Find API endpoints"` | 작업에 대한 짧은 설명 |1882| `description` | string | `"Find API endpoints"` | 작업에 대한 짧은 설명 |
1877| `subagent_type` | string | `"Explore"` | 사용할 전문 에이전트 유형 |1883| `subagent_type` | string | `"Explore"` | 사용할 특화 에이전트 유형 |
1878| `model` | string | `"sonnet"` | 기본값을 재정의할 선택적 모델 별칭 |1884| `model` | string | `"sonnet"` | 기본값을 재정의할 선택적 모델 별칭 |
1879 1885
1880포그라운드 Agent 호출이 완료되면 [PostToolUse 훅](#posttooluse)은 `tool_response`에서 서브에이전트의 결과와 실행 텔레메트리를 받습니다. 실행을 검사하려면 이 필드를 읽습니다. `totalTokens`와 `usage`는 마지막 요청만 다루므로, 서브에이전트 전반의 토큰 및 비용 집계에는 `query_source` `"subagent"`로 필터링한 [토큰 및 비용 카운터](/docs/ko/monitoring-usage#token-counter)를 사용합니다.1886포그라운드 Agent 호출이 완료되면 [PostToolUse 훅](#posttooluse)은 `tool_response`에서 서브에이전트의 결과와 실행 텔레메트리를 수신합니다. 실행을 검사하려면 이 필드를 읽습니다. 서브에이전트 전체의 토큰 및 비용 집계에는 `query_source` `"subagent"`로 필터링한 [토큰 및 비용 카운터](/docs/ko/monitoring-usage#token-counter)를 사용합니다. `totalTokens`와 `usage`는 마지막 요청만 다루기 때문입니다.
1881 1887
1882| 필드 | 유형 | 예시 | 설명 |1888| 필드 | 타입 | 예시 | 설명 |
1883| :- | :- | :- | :- |1889| :- | :- | :- | :- |
1884| `status` | string | `"completed"` | 포그라운드 서브에이전트는 `"completed"`, 백그라운드 서브에이전트는 `"async_launched"`입니다. 서브에이전트는 기본적으로 백그라운드에서 실행되므로, `run_in_background`를 생략한 Agent 호출도 `"async_launched"`를 생성합니다 |1890| `status` | string | `"completed"` | 포그라운드 서브에이전트는 `"completed"`, 백그라운드 서브에이전트는 `"async_launched"`. 서브에이전트는 기본적으로 백그라운드에서 실행되므로 `run_in_background`를 생략한 Agent 호출도 `"async_launched"`를 생성합니다 |
1885| `agentId` | string | `"a4d2c8f1e0b3a297"` | 서브에이전트 실행의 식별자 |1891| `agentId` | string | `"a4d2c8f1e0b3a297"` | 서브에이전트 실행의 식별자 |
1886| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 서브에이전트의 최종 텍스트 블록, 또는 보고서가 `SubagentHandback`을 통해 전달되는 서브에이전트의 경우 그 대신 해당 핸드백에 대한 짧은 메모 |1892| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 서브에이전트의 최종 텍스트 블록. 보고서가 `SubagentHandback`을 통해 전달되는 서브에이전트의 경우 그 대신 해당 인계에 대한 짧은 메모 |
1887| `resolvedModel` | string | `"claude-sonnet-4-5"` | 서브에이전트가 시작한 모델이며, 요청한 모델과 다를 수 있습니다 |1893| `resolvedModel` | string | `"claude-sonnet-4-5"` | 서브에이전트가 시작한 모델. 요청된 모델과 다를 수 있습니다 |
1888| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 사용된 모델을 순서대로 나열하며, 연속된 반복은 하나로 합칩니다. 실행 중에 모델이 교체된 경우에만 설정됩니다. Claude Code v2.1.212 이상이 필요합니다 |1894| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 사용된 모델을 순서대로 나열하며 연속된 반복은 하나로 합칩니다. 실행 중에 모델이 교체된 경우에만 설정됩니다. Claude Code v2.1.212 이상이 필요합니다 |
1889| `totalTokens` | number | `12450` | 서브에이전트의 마지막 API 요청의 토큰 수로, 입력, 출력, 캐시 토큰을 합한 값입니다. 전체 실행에 걸친 합계가 아닙니다 |1895| `totalTokens` | number | `12450` | 서브에이전트의 마지막 API 요청의 토큰 수: 입력, 출력, 캐시 토큰의 합계. 전체 실행에 대한 합계가 아닙니다 |
1890| `totalDurationMs` | number | `48211` | 서브에이전트 실행의 실제 소요 시간 |1896| `totalDurationMs` | number | `48211` | 서브에이전트 실행의 실제 소요 시간 |
1891| `totalToolUseCount` | number | `7` | 서브에이전트가 수행한 도구 호출 수 |1897| `totalToolUseCount` | number | `7` | 서브에이전트가 수행한 도구 호출 수 |
1892| `usage` | object | `{"input_tokens": 8320, ...}` | 마지막 API 요청의 유형별 토큰 내역: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1898| `usage` | object | `{"input_tokens": 8320, ...}` | 마지막 API 요청의 유형별 토큰 내역: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1893 1899
1894Claude Code v2.1.271 이상에서는 Claude Code가 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 제공하는 [`SubagentHandback`](/docs/ko/tools-reference) 도구와 함께 실행되는 서브에이전트가 보고서를 텍스트로 반환하지 않고 해당 도구를 통해 전달합니다. 그러면 `completed` 결과의 `content` 필드에는 보고서 자체가 아니라 해당 핸드백에 대한 짧은 메모가 담깁니다. 보고서를 읽으려면 `SubagentHandback`에 `PreToolUse` 또는 `PostToolUse` 훅을 일치시키고 `tool_input.message`를 읽습니다.1900Claude Code v2.1.271 이상에서는 Claude Code가 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 제공하는 [`SubagentHandback`](/docs/ko/tools-reference) 도구로 실행되는 서브에이전트가 보고서를 텍스트로 반환하지 않고 해당 도구를 통해 전달합니다. 이 경우 `completed` 결과의 `content` 필드에는 보고서 자체가 아니라 해당 인계에 대한 짧은 메모가 담깁니다. 보고서를 읽으려면 `SubagentHandback`에 `PreToolUse` 또는 `PostToolUse` 훅을 일치시키고 `tool_input.message`를 읽습니다.
1895 1901
1896백그라운드 서브에이전트의 경우 작업이 백그라운드로 이동할 때 도구가 반환되므로 `tool_response`에는 사용량 필드가 없습니다. 백그라운드 실행은 즉시 반환되며, Claude Code가 실행 도중 백그라운드로 보낸 포그라운드 작업은 그 전환 시점에 반환됩니다. 여기에는 `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 있습니다.1902백그라운드 서브에이전트의 경우 작업이 백그라운드로 이동할 때 도구가 반환되므로 `tool_response`에는 사용량 필드가 없습니다. 백그라운드 실행은 즉시 반환되고, Claude Code가 실행 도중 백그라운드로 전환한 포그라운드 작업은 그 전환 시점에 반환됩니다. 이 응답에는 `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, `resolvedModel`이 포함됩니다.
1897 1903
1898`completed` 응답에서 `resolvedModel`은 서브에이전트가 시작한 모델을 나타내며, `availableModels`나 다른 재정의가 적용되는 경우처럼 `tool_input`의 `model` 값과 다를 수 있습니다. `async_launched` 응답에서 `resolvedModel`은 에이전트가 백그라운드로 이동할 때 사용 중이던 모델을 나타내므로, 백그라운드 전환 전에 일어난 교체가 반영됩니다. `modelsUsed`와 백그라운드 전환 시점의 `resolvedModel` 동작은 Claude Code v2.1.212 이상이 필요합니다.1904`completed` 응답에서 `resolvedModel`은 서브에이전트가 시작한 모델을 나타내며, `availableModels`나 다른 재정의가 적용되는 경우처럼 `tool_input`의 `model` 값과 다를 수 있습니다. `async_launched` 응답에서 `resolvedModel`은 에이전트가 백그라운드로 이동할 때 사용 중이던 모델을 나타내므로, 백그라운드 전환 전에 발생한 교체가 반영됩니다. `modelsUsed`와 백그라운드 전환 시점의 `resolvedModel` 동작에는 Claude Code v2.1.212 이상이 필요합니다.
1899 1905
1900<a id="askuserquestion" />1906<a id="askuserquestion" />
1901 1907
1905 1911
1906사용자에게 1\~4개의 객관식 질문을 합니다.1912사용자에게 1\~4개의 객관식 질문을 합니다.
1907 1913
1908| 필드 | 유형 | 예시 | 설명 |1914| 필드 | 타입 | 예시 | 설명 |
1909| :- | :- | :- | :- |1915| :- | :- | :- | :- |
1910| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 제시할 질문으로, 각각 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그를 가집니다 |1916| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 표시할 질문. 각 질문에는 `question` 문자열, 짧은 `header`, `options` 배열, 선택적 `multiSelect` 플래그가 있습니다 |
1911| `answers` | object | `{"Which framework?": "React"}` | 선택 사항입니다. 질문 텍스트를 선택된 옵션 레이블에 매핑합니다. 다중 선택 답변은 레이블을 쉼표로 연결합니다. Claude는 이 필드를 설정하지 않으며, 프로그래밍 방식으로 답하려면 `updatedInput`을 통해 제공합니다 |1917| `answers` | object | `{"Which framework?": "React"}` | 선택 사항. 질문 텍스트를 선택된 옵션 레이블에 매핑합니다. 다중 선택 답변은 레이블을 쉼표로 연결합니다. Claude는 이 필드를 설정하지 않으며, 프로그래밍 방식으로 답하려면 `updatedInput`을 통해 제공합니다 |
1912 1918
1913<h5 id="exitplanmode">1919<h5 id="exitplanmode">
1914 ExitPlanMode1920 ExitPlanMode
1915</h5>1921</h5>
1916 1922
1917Claude가 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 디스크의 파일에 쓰므로, 모델에서 온 실제 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 입력을 훅에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.1923Claude가 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 벗어나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 디스크의 파일에 작성하므로, 모델이 보낸 실제 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 입력을 훅에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.
1918 1924
1919| 필드 | 유형 | 예시 | 설명 |1925| 필드 | 타입 | 예시 | 설명 |
1920| :- | :- | :- | :- |1926| :- | :- | :- | :- |
1921| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 형식의 계획 내용입니다. 디스크의 계획 파일에서 주입됩니다 |1927| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 형식의 계획 내용. 디스크의 계획 파일에서 주입됩니다 |
1922| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 계획 파일의 경로입니다. 주입됩니다 |1928| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 계획 파일 경로. 주입됩니다 |
1923| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | deprecated입니다. Claude Code는 이 필드를 받지만 무시합니다. v2.1.205 이전에는 Claude가 계획을 구현하기 위해 요청한 프롬프트 기반 권한을 담았습니다 |1929| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | deprecated. Claude Code는 이 필드를 받아들이지만 무시합니다. v2.1.205 이전에는 Claude가 계획을 구현하기 위해 요청한 프롬프트 기반 권한을 담았습니다 |
1924 1930
1925`PostToolUse`에서 `tool_response`는 승인된 계획을 담은 `plan` 및 `filePath` 필드와 내부 상태 플래그가 있는 객체입니다. 디스크에서 파일을 다시 읽는 대신 `tool_response.plan`에서 계획 내용을 읽습니다.1931`PostToolUse`에서 `tool_response`는 승인된 계획을 담은 `plan` 및 `filePath` 필드와 내부 상태 플래그가 포함된 객체입니다. 계획 내용은 디스크에서 파일을 다시 읽지 말고 `tool_response.plan`에서 읽습니다.
1926 1932
1927<h4 id="pretooluse-decision-control">1933<h4 id="pretooluse-decision-control">
1928 PreToolUse 결정 제어1934 PreToolUse 결정 제어
1929</h4>1935</h4>
1930 1936
1931`PreToolUse` 훅은 도구 호출의 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 훅과 달리 PreToolUse는 `hookSpecificOutput` 객체 안에서 결정을 반환합니다. 이를 통해 네 가지 결과(허용, 거부, 확인 요청, 지연)와 실행 전 도구 입력 수정 기능이라는 더 풍부한 제어가 가능합니다.1937`PreToolUse` 훅은 도구 호출의 진행 여부를 제어할 수 있습니다. 최상위 `decision` 필드를 사용하는 다른 훅과 달리 PreToolUse는 `hookSpecificOutput` 객체 안에서 결정을 반환합니다. 이를 통해 더 풍부한 제어가 가능합니다. 네 가지 결과(허용, 거부, 확인 요청, 지연)와 함께 실행 전에 도구 입력을 수정하는 기능을 제공합니다.
1932 1938
1933| 필드 | 설명 |1939| 필드 | 설명 |
1934| :- | :- |1940| :- | :- |
1935| `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)은 훅이 무엇을 반환하든 여전히 평가됩니다 |1941| `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)은 여전히 평가됩니다 |
1936| `permissionDecisionReason` | `"ask"`의 경우 Claude가 아닌 사용자에게 표시됩니다. `"deny"`의 경우 Claude에게 표시됩니다. `"allow"`와 `"defer"`의 경우 [디버그 로그](#debug-hooks)에만 기록됩니다 |1942| `permissionDecisionReason` | `"ask"`의 경우 권한 프롬프트에서 사용자에게 표시됩니다. 아무도 해당 프롬프트에 응답할 수 없는 `-p` 실행에서 Claude Code가 [호출을 거부](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)하면 Claude는 대신 도구 결과에서 이유를 읽습니다. `"deny"`의 경우 Claude에게 표시됩니다. `"allow"`와 `"defer"`의 경우 [디버그 로그](#debug-hooks)에만 기록됩니다 |
1937| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 입력 객체 전체를 대체하므로 수정된 필드와 함께 변경되지 않은 필드도 포함해야 합니다. Claude Code는 Claude가 보낸 입력이 아니라 훅이 반환한 입력에 대해 권한 규칙과 Bash 명령의 [자동 백그라운드 적격성](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)을 평가합니다. 자동 승인하려면 `"allow"`와, 수정된 입력을 사용자에게 보여 주려면 `"ask"`와 함께 사용합니다. `"defer"`에서는 무시됩니다 |1943| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 대체하므로 수정한 필드와 함께 변경하지 않은 필드도 포함해야 합니다. Claude Code는 Claude가 보낸 입력이 아니라 훅이 반환한 입력을 기준으로 권한 규칙과 Bash 명령의 [자동 백그라운드 전환 적격성](/docs/ko/tools-reference#foreground-commands-that-move-to-the-background)을 평가합니다. 자동 승인하려면 `"allow"`와, 수정된 입력을 사용자에게 보여 주려면 `"ask"`와 함께 사용합니다. `"defer"`의 경우 무시됩니다 |
1938| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. `permissionDecision`이 `"defer"`이면 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |1944| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열. `permissionDecision`이 `"defer"`이면 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
1939 1945
1940여러 PreToolUse 훅이 서로 다른 결정을 반환하면 우선순위는 `deny` > `defer` > `ask` > `allow`입니다.1946여러 PreToolUse 훅이 서로 다른 결정을 반환하는 경우 우선순위는 `deny` > `defer` > `ask` > `allow`입니다.
1941 1947
1942종료 코드 2로 차단하는 훅은 `"deny"`와 같은 방식으로 전달됩니다. Claude는 stderr 메시지를 거부 이유로 봅니다.1948종료 코드 2로 차단하는 훅은 `"deny"`와 같은 방식으로 전달됩니다. Claude는 stderr 메시지를 거부 이유로 봅니다.
1943 1949
1944훅이 `"ask"`를 반환하면 사용자에게 표시되는 권한 프롬프트에 훅의 출처를 식별하는 레이블이 포함됩니다. 설정 파일이나 에이전트 frontmatter의 훅은 `[settings]`, 플러그인의 훅은 `[plugin:<name>]`, 스킬 frontmatter의 훅은 `[skill]`입니다. 이를 통해 사용자는 어떤 구성 소스가 확인을 요청하는지 이해할 수 있습니다.1950훅이 `"ask"`를 반환하면 사용자에게 표시되는 권한 프롬프트에 훅의 출처를 식별하는 레이블이 포함됩니다. 설정 파일이나 에이전트 frontmatter의 훅은 `[settings]`, 플러그인의 훅은 `[plugin:<name>]`, 스킬 frontmatter의 훅은 `[skill]`입니다. 이를 통해 사용자는 어떤 구성 출처가 확인을 요청하는지 이해할 수 있습니다.
1945 1951
1946훅의 `"ask"`는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서도 권한 프롬프트를 강제합니다. 분류기는 여전히 도구 호출을 거부할 수 있지만, 호출을 조용히 승인할 수는 없습니다. v2.1.211 이전에는 분류기가 [샌드박스](/docs/ko/sandboxing) 밖에서 실행되는 Bash 명령을 훅이 요청한 프롬프트를 표시하지 않고 승인할 수 있었습니다. 분류기는 여전히 해당 명령에 자체 안전 규칙을 적용했으며, 훅의 `"deny"`는 항상 존중되었습니다.1952훅의 `"ask"`는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서도 권한 프롬프트를 강제합니다. 분류기는 여전히 도구 호출을 거부할 수 있지만, 호출을 조용히 승인할 수는 없습니다. v2.1.211 이전에는 분류기가 [샌드박스](/docs/ko/sandboxing) 외부에서 실행되는 Bash 명령을 훅이 요청한 프롬프트를 표시하지 않고 승인할 수 있었습니다. 이 경우에도 분류기는 해당 명령에 자체 안전 규칙을 적용했으며, 훅의 `"deny"`는 항상 적용되었습니다.
1947 1953
1948```json theme={null}1954```json theme={null}
1949{1955{
1961 1967
1962<span id="allow-with-updatedinput" />1968<span id="allow-with-updatedinput" />
1963 1969
1964`-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서 Claude Code는 Agent SDK `canUseTool` 콜백처럼 프롬프트를 받을 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 실행에 있을 때만 `AskUserQuestion`과 `ExitPlanMode`를 제공합니다. 이 도구들은 사용자 상호 작용이 필요합니다. `permissionDecision: "allow"`와 `updatedInput`을 함께 반환하면 이 요구 사항이 충족됩니다. 훅은 stdin에서 도구의 입력을 읽고, 자체 UI를 통해 답변을 수집한 다음, `updatedInput`으로 반환하여 도구가 프롬프트 없이 실행되도록 합니다. 이 도구들에는 `"allow"`만 반환하는 것으로는 충분하지 않습니다. `AskUserQuestion`의 경우 원본 `questions` 배열을 그대로 돌려주고, 각 질문의 텍스트를 선택된 답변에 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.1970`-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서 Claude Code는 Agent SDK의 `canUseTool` 콜백처럼 프롬프트를 수신할 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 실행에 있을 때만 `AskUserQuestion`과 `ExitPlanMode`를 제공합니다. 이 도구들은 사용자 상호 작용이 필요합니다. `permissionDecision: "allow"`를 `updatedInput`과 함께 반환하면 이 요구 사항이 충족됩니다. 훅은 stdin에서 도구의 입력을 읽고, 자체 UI를 통해 답변을 수집한 다음, 도구가 프롬프트 없이 실행되도록 `updatedInput`에 답변을 담아 반환합니다. 이 도구들에는 `"allow"`만 반환하는 것으로는 충분하지 않습니다. `AskUserQuestion`의 경우 원래 `questions` 배열을 그대로 반환하고, 각 질문의 텍스트를 선택된 답변에 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.
1965 1971
1966v2.1.199부터 서버가 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시한 MCP 도구는 더 엄격합니다. Claude Code는 훅이 도구에 필요한 상호 작용을 수집했는지 확인할 수 없으므로, 훅은 `updatedInput` 유무와 관계없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다.1972서버가 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)로 표시한 MCP 도구는 더 엄격합니다. 훅은 `updatedInput` 유무와 관계없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다. Claude Code가 훅이 해당 도구에 필요한 상호 작용을 수집했는지 확인할 수 없기 때문입니다.
1967 1973
1968<Note>1974<Note>
1969 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만, 이 이벤트에서는 deprecated되었습니다. 대신 `hookSpecificOutput.permissionDecision`과 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. deprecated된 값 `"approve"`와 `"block"`은 각각 `"allow"`와 `"deny"`에 매핑됩니다. PostToolUse와 Stop 같은 다른 이벤트는 현재 형식으로 최상위 `decision`과 `reason`을 계속 사용합니다.1975 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만, 이 이벤트에서는 deprecated되었습니다. 대신 `hookSpecificOutput.permissionDecision`과 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. deprecated된 값 `"approve"`와 `"block"`은 각각 `"allow"`와 `"deny"`에 매핑됩니다. PostToolUse와 Stop 같은 다른 이벤트는 현재 형식으로 최상위 `decision`과 `reason`을 계속 사용합니다.
1970</Note>1976</Note>
1971 1977
1972<h4 id="defer-a-tool-call-for-later">1978<h4 id="defer-a-tool-call-for-later">
1973 나중을 위해 도구 호출 지연1979 도구 호출을 나중으로 지연
1974</h4>1980</h4>
1975 1981
1976`"defer"`는 Agent SDK 앱이나 Claude Code 위에 구축된 사용자 지정 UI처럼 `claude -p`를 하위 프로세스로 실행하고 JSON 출력을 읽는 통합을 위한 것입니다. 이를 통해 호출 프로세스는 도구 호출 시점에서 Claude를 일시 중지하고, 자체 인터페이스를 통해 입력을 수집한 다음, 중단된 지점에서 재개할 수 있습니다. Claude Code는 `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서만 이 값을 존중합니다. 대화형 세션에서는 경고를 로그에 기록하고 훅 결과를 무시합니다.1982`"defer"`는 Agent SDK 앱이나 Claude Code 위에 구축된 사용자 지정 UI처럼 `claude -p`를 하위 프로세스로 실행하고 JSON 출력을 읽는 통합을 위한 것입니다. 이를 통해 호출하는 프로세스가 도구 호출 시점에 Claude를 일시 중지하고, 자체 인터페이스를 통해 입력을 수집한 다음, 중단한 지점에서 재개할 수 있습니다. Claude Code는 `-p` 플래그를 사용하는 [비대화형 모드](/docs/ko/headless)에서만 이 값을 적용합니다. 대화형 세션에서는 경고를 로그에 기록하고 훅 결과를 무시합니다.
1977 1983
1978`AskUserQuestion` 도구가 대표적인 사례입니다. Claude는 사용자에게 무언가를 묻고 싶지만 답할 터미널이 없습니다. `-p` 실행은 `--permission-prompt-tool`로 전달하는 MCP 도구 같은 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 있을 때만 `AskUserQuestion`을 제공하므로, 권한 호스트와 함께 실행을 시작해야 합니다. 왕복 과정은 다음과 같습니다.1984`AskUserQuestion` 도구가 대표적인 경우입니다. Claude가 사용자에게 무언가를 묻고 싶지만 답변할 터미널이 없습니다. `-p` 실행은 `--permission-prompt-tool`로 전달하는 MCP 도구 같은 [권한 호스트](/docs/ko/headless#turn-off-permission-prompts-in-unattended-runs)가 있을 때만 `AskUserQuestion`을 제공하므로, 권한 호스트와 함께 실행을 시작합니다. 왕복 과정은 다음과 같습니다.
1979 1985
19801. Claude가 `AskUserQuestion`을 호출합니다. `PreToolUse` 훅이 발생합니다.19861. Claude가 `AskUserQuestion`을 호출합니다. `PreToolUse` 훅이 발생합니다.
19812. 훅이 `permissionDecision: "defer"`를 반환합니다. 도구는 실행되지 않습니다. 프로세스는 `stop_reason: "tool_deferred"`로 종료되며, 보류 중인 도구 호출은 트랜스크립트에 보존됩니다.19872. 훅이 `permissionDecision: "defer"`를 반환합니다. 도구는 실행되지 않습니다. 프로세스는 `stop_reason: "tool_deferred"`와 함께 종료되며, 보류 중인 도구 호출은 트랜스크립트에 보존됩니다.
19823. 호출 프로세스는 SDK 결과에서 `deferred_tool_use`를 읽고, 자체 UI에 질문을 표시한 다음, 답변을 기다립니다.19883. 호출하는 프로세스가 SDK 결과에서 `deferred_tool_use`를 읽고, 자체 UI에 질문을 표시한 다음 답변을 기다립니다.
19834. 호출 프로세스는 같은 권한 호스트로 `claude -p --resume <session-id>`를 실행합니다. 같은 도구 호출이 다시 `PreToolUse`를 발생시킵니다.19894. 호출하는 프로세스가 같은 권한 호스트로 `claude -p --resume <session-id>`를 실행합니다. 같은 도구 호출이 `PreToolUse`를 다시 발생시킵니다.
19845. 훅이 `updatedInput`에 답변을 담아 `permissionDecision: "allow"`를 반환합니다. 도구가 실행되고 Claude가 계속합니다.19905. 훅이 `updatedInput`에 답변을 담아 `permissionDecision: "allow"`를 반환합니다. 도구가 실행되고 Claude가 계속 진행합니다.
1985 1991
1986`deferred_tool_use` 필드에는 도구의 `id`, `name`, `input`이 담깁니다. `input`은 Claude가 도구 호출을 위해 생성한 매개변수로, 실행 전에 캡처됩니다.1992`deferred_tool_use` 필드에는 도구의 `id`, `name`, `input`이 담깁니다. `input`은 Claude가 도구 호출을 위해 생성한 매개변수로, 실행 전에 캡처됩니다.
1987 1993
1999}2005}
2000```2006```
2001 2007
2002타임아웃이나 재시도 제한은 없습니다. 세션은 재개할 때까지 디스크에 남아 있으며, [보존 정리 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 기본적으로 30일 후 세션 파일을 삭제하는 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 보존 정리의 적용을 받습니다. 재개할 때 답변이 준비되지 않았다면 훅은 다시 `"defer"`를 반환할 수 있으며, 프로세스는 같은 방식으로 종료됩니다. 호출 프로세스는 결국 훅에서 `"allow"` 또는 `"deny"`를 반환하여 루프를 끝낼 시점을 제어합니다.2008타임아웃이나 재시도 제한은 없습니다. 세션은 재개할 때까지 디스크에 남아 있으며, [보존 정리 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 기본적으로 30일 후 세션 파일을 삭제하는 [`cleanupPeriodDays`](/docs/ko/settings-reference#cleanupperioddays) 보존 정리의 적용을 받습니다. 재개할 때 답변이 준비되지 않았다면 훅이 다시 `"defer"`를 반환할 수 있으며, 프로세스는 같은 방식으로 종료됩니다. 호출하는 프로세스는 최종적으로 훅에서 `"allow"` 또는 `"deny"`를 반환하여 루프를 끝낼 시점을 제어합니다.
2003 2009
2004`"defer"`는 Claude가 턴에서 단일 도구 호출을 할 때만 작동합니다. Claude가 한 번에 여러 도구 호출을 하면 `"defer"`는 경고와 함께 무시되고 도구는 일반 권한 흐름을 통해 진행됩니다. 이 제약은 재개 시 하나의 도구만 다시 실행할 수 있기 때문에 존재합니다. 배치에서 하나의 호출을 지연하면서 나머지를 해결되지 않은 상태로 두지 않을 방법이 없습니다.2010`"defer"`는 Claude가 해당 턴에서 단일 도구 호출을 할 때만 작동합니다. Claude가 여러 도구 호출을 한 번에 하면 `"defer"`는 경고와 함께 무시되고 도구는 일반 권한 흐름을 거쳐 진행됩니다. 이 제약은 재개 시 하나의 도구만 다시 실행할 수 있기 때문에 존재합니다. 묶음에서 하나의 호출만 지연하면 나머지 호출이 해결되지 않은 상태로 남게 됩니다.
2005 2011
2006재개할 때 지연된 도구를 더 이상 사용할 수 없으면 프로세스는 훅이 발생하기 전에 `stop_reason: "tool_deferred_unavailable"` 및 `is_error: true`로 종료됩니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되어 있지 않을 때 발생합니다. `deferred_tool_use` 페이로드는 여전히 포함되므로 어떤 도구가 없어졌는지 식별할 수 있습니다.2012재개할 때 지연된 도구를 더 이상 사용할 수 없으면, 프로세스는 훅이 발생하기 전에 `stop_reason: "tool_deferred_unavailable"` 및 `is_error: true`와 함께 종료됩니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되지 않은 경우에 발생합니다. 어떤 도구가 사라졌는지 식별할 수 있도록 `deferred_tool_use` 페이로드는 여전히 포함됩니다.
2007 2013
2008<Note>2014<Note>
2009 플랜 모드에서 지연된 세션을 재개하려면 Claude Code가 승인을 위해 계획을 제시할 수 있도록 `--resume`과 함께 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)을 전달합니다. 특정 다른 실행 플래그를 전달하면 재개된 실행이 플랜 모드로 돌아가지 않습니다. [`-p`로 플랜 모드에서 재개](/docs/ko/sessions#resume-in-plan-mode-with-p)를 참조하십시오. Claude Code v2.1.246 이상이 필요합니다.2015 지연된 세션을 플랜 모드로 재개하려면 Claude Code가 승인을 위해 계획을 제시할 수 있도록 `--resume`과 함께 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)을 전달합니다. 특정 다른 실행 플래그를 전달하면 재개된 실행이 플랜 모드로 돌아가지 않습니다. [`-p`로 플랜 모드에서 재개](/docs/ko/sessions#resume-in-plan-mode-with-p)를 참조하세요. Claude Code v2.1.246 이상이 필요합니다.
2010 2016
2011 `-p`로 재개하면 Claude Code는 다른 저장된 권한 모드를 복원하지 않습니다. 새 `claude -p` 실행이 시작할 권한 모드로 실행을 시작하므로, 지연된 세션이 `--permission-mode` 또는 `--dangerously-skip-permissions`를 사용했다면 다시 전달해야 합니다. `-p` 없이 `claude --resume <session-id>`로 재개하면 Claude Code는 [재개 시 권한 모드](/docs/ko/sessions#permission-mode-on-resume)에 나열된 예외를 제외하고 저장된 권한 모드를 복원합니다.2017 `-p`로 재개하면 Claude Code는 저장된 다른 권한 모드를 복원하지 않습니다. 새로운 `claude -p` 실행이 시작하는 권한 모드로 실행을 시작하므로, 지연된 세션이 `--permission-mode` 또는 `--dangerously-skip-permissions`를 사용했다면 다시 전달해야 합니다. `-p` 없이 `claude --resume <session-id>`로 재개하면 Claude Code는 [재개 시 권한 모드](/docs/ko/sessions#permission-mode-on-resume)에 나열된 예외를 제외하고 저장된 권한 모드를 복원합니다.
2012</Note>2018</Note>
2013 2019
2014<h3 id="permissionrequest">2020<h3 id="permissionrequest">
2015 PermissionRequest2021 PermissionRequest
2016</h3>2022</h3>
2017 2023
2018Claude Code가 도구 사용 권한을 요청하려고 할 때 실행됩니다. [비대화형 모드](/docs/ko/headless)의 백그라운드 서브에이전트처럼 프롬프트를 표시할 수 없는 세션에서도 Claude Code는 이 훅을 실행하며, 어떤 훅도 결정을 반환하지 않으면 도구 호출을 거부합니다. `--permission-prompt-tool`이나 Agent SDK의 [`canUseTool` 콜백](/docs/ko/agent-sdk/permissions)에 도달하는 호출의 경우 훅은 호스트와 함께 실행되며, 먼저 결정하는 쪽이 적용됩니다.2024Claude Code가 도구 사용 권한을 요청하려고 할 때 실행됩니다. [비대화형 모드](/docs/ko/headless)의 백그라운드 서브에이전트처럼 프롬프트를 표시할 수 없는 세션에서도 Claude Code는 이 훅을 실행하며, 결정을 반환하는 훅이 없으면 도구 호출을 거부합니다. `--permission-prompt-tool`이나 Agent SDK의 [`canUseTool` 콜백](/docs/ko/agent-sdk/permissions)에 도달하는 호출의 경우 훅은 호스트와 함께 실행되며, 먼저 결정하는 쪽이 적용됩니다.
2019[PermissionRequest 결정 제어](#permissionrequest-decision-control)를 사용해 사용자를 대신하여 허용하거나 거부하십시오.2025사용자를 대신하여 허용하거나 거부하려면 [PermissionRequest 결정 제어](#permissionrequest-decision-control)를 사용합니다.
2020 2026
2021Claude가 도구 사용 권한을 요청하는 순간에 신호가 필요할 때 이 이벤트를 사용합니다. Claude Code는 프롬프트가 약 6초 동안 대기한 후에만 `permission_prompt` 유형의 [Notification](#notification) 훅을 실행합니다.2027Claude가 도구 사용 권한을 요청하는 순간 신호가 필요할 때 이 이벤트를 사용합니다. Claude Code는 프롬프트가 약 6초 동안 대기한 후에만 `permission_prompt` 유형의 [Notification](#notification) 훅을 실행합니다.
2022 2028
2023Claude Code는 샌드박스 처리된 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대해서는 PermissionRequest 훅을 실행하지 않습니다. 해당 프롬프트에 대한 신호를 받으려면 `permission_prompt` 알림 유형을 사용합니다.2029Claude Code는 샌드박스 처리된 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대해서는 PermissionRequest 훅을 실행하지 않습니다. 해당 프롬프트에 대한 신호를 받으려면 `permission_prompt` 알림 유형을 사용합니다.
2024 2030
2025PreToolUse와 같은 값으로 도구 이름에 대해 일치시킵니다.2031도구 이름에 대해 일치시키며, 값은 PreToolUse와 같습니다.
2026 2032
2027<h4 id="permissionrequest-input">2033<h4 id="permissionrequest-input">
2028 PermissionRequest 입력2034 PermissionRequest 입력
2029</h4>2035</h4>
2030 2036
2031PermissionRequest 훅은 PreToolUse 훅처럼 `tool_name`과 `tool_input` 필드를 받지만 `tool_use_id`는 받지 않습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 받습니다. 선택적 `permission_suggestions` 배열에는 허용 규칙 추가나 권한 모드 변경처럼 Claude Code가 이 요청에 대해 제안하는 [권한 업데이트](#permission-update-entries)가 담깁니다.2037PermissionRequest 훅은 PreToolUse 훅처럼 `tool_name` 및 `tool_input` 필드를 수신하지만 `tool_use_id`는 없습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 수신합니다. 선택적 `permission_suggestions` 배열에는 허용 규칙 추가나 권한 모드 변경처럼 Claude Code가 이 요청에 대해 제안하는 [권한 업데이트](#permission-update-entries)가 담깁니다.
2032 2038
2033각 권한 대화 상자는 자체 옵션을 구성하므로 `permission_suggestions` 배열은 사용자에게 표시되는 옵션의 정확한 목록이 아닙니다. 파일 편집용 대화 상자처럼 일부 대화 상자는 배열을 전혀 읽지 않고 요청 자체에서 옵션을 도출합니다. 배열을 읽는 대화 상자도 제안이 배열에 남아 있는 옵션을 보류할 수 있습니다. 예를 들어 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)가 규칙 저장 옵션을 숨기는 경우입니다. 또한 권한 업데이트를 통하지 않고 권한 모드를 직접 변경하는 [**Yes, and switch to auto mode**](/docs/ko/permission-modes#switch-permission-modes)처럼 제안 항목이 없는 옵션을 제공할 수도 있습니다.2039각 권한 대화 상자는 자체 옵션을 구성하므로 `permission_suggestions` 배열은 사용자에게 보이는 옵션의 정확한 목록이 아닙니다. 파일 편집 대화 상자처럼 일부 대화 상자는 배열을 전혀 읽지 않고 요청 자체에서 옵션을 도출합니다. 배열을 읽는 대화 상자도 제안이 배열에 남아 있는 옵션을 표시하지 않을 수 있습니다. 예를 들어 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)가 규칙 저장 옵션을 숨기는 경우입니다. 또한 [**Yes, and switch to auto mode**](/docs/ko/permission-modes#switch-permission-modes)처럼 제안 항목이 없는 옵션을 제공할 수도 있으며, 이 옵션은 권한 업데이트를 거치지 않고 권한 모드를 직접 변경합니다.
2034 2040
2035PreToolUse 훅은 권한이 필요한지 여부와 관계없이 모든 도구 호출 전에 실행됩니다. PermissionRequest 훅은 Claude Code가 권한을 요청하려고 할 때, 또는 프롬프트를 표시할 수 없는 호출을 자동 거부하려고 할 때만 실행됩니다. 두 이벤트 모두 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에서는 발생하지 않습니다.2041PreToolUse 훅은 권한이 필요한지 여부와 관계없이 모든 도구 호출 전에 실행됩니다. PermissionRequest 훅은 Claude Code가 권한을 요청하려고 할 때, 또는 프롬프트를 표시할 수 없는 호출을 자동으로 거부하려고 할 때만 실행됩니다. 두 이벤트 모두 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)에서는 발생하지 않습니다.
2036 2042
2037```json theme={null}2043```json theme={null}
2038{2044{
2061 PermissionRequest 결정 제어2067 PermissionRequest 결정 제어
2062</h4>2068</h4>
2063 2069
2064`PermissionRequest` 훅은 권한 요청을 허용하거나 거부할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음 이벤트별 필드가 있는 `decision` 객체를 반환할 수 있습니다.2070`PermissionRequest` 훅은 권한 요청을 허용하거나 거부할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음 이벤트별 필드가 포함된 `decision` 객체를 반환할 수 있습니다.
2065 2071
2066| 필드 | 설명 |2072| 필드 | 설명 |
2067| :- | :- |2073| :- | :- |
2068| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [거부 및 확인 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가되므로, `"allow"`를 반환하는 훅이 일치하는 거부 규칙을 재정의하지는 않습니다 |2074| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [거부 및 확인 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가되므로, `"allow"`를 반환하는 훅이 일치하는 거부 규칙을 재정의하지는 않습니다 |
2069| `updatedInput` | `"allow"` 전용: 실행 전에 도구의 입력 매개변수를 수정합니다. 입력 객체 전체를 대체하므로 수정된 필드와 함께 변경되지 않은 필드도 포함해야 합니다. 수정된 입력은 거부 및 확인 규칙에 대해 다시 평가됩니다 |2075| `updatedInput` | `"allow"` 전용: 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 대체하므로 수정한 필드와 함께 변경하지 않은 필드도 포함해야 합니다. 수정된 입력은 거부 및 확인 규칙에 대해 다시 평가됩니다 |
2070| `updatedPermissions` | `"allow"` 전용: 허용 규칙 추가나 세션 권한 모드 변경처럼 적용할 [권한 업데이트 항목](#permission-update-entries)의 배열 |2076| `updatedPermissions` | `"allow"` 전용: 허용 규칙 추가나 세션 권한 모드 변경처럼 적용할 [권한 업데이트 항목](#permission-update-entries)의 배열 |
2071| `message` | `"deny"` 전용: 권한이 거부된 이유를 Claude에게 알립니다 |2077| `message` | `"deny"` 전용: 권한이 거부된 이유를 Claude에게 알립니다 |
2072| `interrupt` | `"deny"` 전용: `true`이면 Claude를 중지합니다 |2078| `interrupt` | `"deny"` 전용: `true`이면 Claude를 중지합니다 |
2095 2101
2096| `type` | 필드 | 효과 |2102| `type` | 필드 | 효과 |
2097| :- | :- | :- |2103| :- | :- | :- |
2098| `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"`입니다 |
2099| `replaceRules` | `rules`, `behavior`, `destination` | `destination`에서 지정된 `behavior`의 모든 규칙을 제공된 `rules`로 대체합니다 |2105| `replaceRules` | `rules`, `behavior`, `destination` | `destination`에서 지정된 `behavior`의 모든 규칙을 제공된 `rules`로 대체합니다 |
2100| `removeRules` | `rules`, `behavior`, `destination` | 지정된 `behavior`의 일치하는 규칙을 제거합니다 |2106| `removeRules` | `rules`, `behavior`, `destination` | 지정된 `behavior`의 일치하는 규칙을 제거합니다 |
2101| `setMode` | `mode`, `destination` | 권한 모드를 변경합니다. 유효한 모드는 `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, 그리고 `default`의 별칭인 `manual`입니다. `manual` 별칭은 Claude Code v2.1.200 이상이 필요합니다 |2107| `setMode` | `mode`, `destination` | 권한 모드를 변경합니다. 유효한 모드는 `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, 그리고 `default`의 별칭인 `manual`입니다. `manual` 별칭에는 Claude Code v2.1.200 이상이 필요합니다 |
2102| `addDirectories` | `directories`, `destination` | 작업 디렉터리를 추가합니다. `directories`는 경로 문자열의 배열입니다 |2108| `addDirectories` | `directories`, `destination` | 작업 디렉터리를 추가합니다. `directories`는 경로 문자열의 배열입니다 |
2103| `removeDirectories` | `directories`, `destination` | 작업 디렉터리를 제거합니다 |2109| `removeDirectories` | `directories`, `destination` | 작업 디렉터리를 제거합니다 |
2104 2110
2105<Note>2111<Note>
2106 `bypassPermissions`를 지정한 `setMode`는 bypass 모드를 이미 사용할 수 있는 상태로 세션을 시작한 경우에만 적용됩니다. 즉, `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`를 사용했거나 [사용자, `--settings` 또는 관리형 설정](/docs/ko/settings-reference#permissions-defaultmode)에 `permissions.defaultMode: "bypassPermissions"`가 지정되어 있어야 합니다. 그렇지 않으면 이 업데이트는 아무 효과가 없습니다. [`permissions.disableBypassPermissionsMode`](/docs/ko/permissions#managed-settings)가 이 모드를 비활성화한 경우나 세션이 [제한 모드](/docs/ko/cli-reference#cli-flags)로 시작된 경우에도 업데이트는 아무 효과가 없습니다.2112 `bypassPermissions`를 사용하는 `setMode`는 우회 모드를 이미 사용할 수 있는 상태로 세션을 시작한 경우에만 적용됩니다. 즉, `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`를 사용했거나 [사용자 설정, `--settings` 또는 관리형 설정](/docs/ko/settings-reference#permissions-defaultmode)에 `permissions.defaultMode: "bypassPermissions"`가 있어야 합니다. 그렇지 않으면 업데이트는 아무 효과가 없습니다. [`permissions.disableBypassPermissionsMode`](/docs/ko/permissions#managed-settings)가 이 모드를 비활성화한 경우나 세션이 [제한 모드](/docs/ko/cli-reference#cli-flags)로 시작된 경우에도 업데이트는 아무 효과가 없습니다.
2107 2113
2108 `bypassPermissions`는 `destination`과 관계없이 `defaultMode`로 저장되지 않습니다.2114 `bypassPermissions`는 `destination`과 관계없이 `defaultMode`로 저장되지 않습니다.
2109</Note>2115</Note>
2117| `projectSettings` | `.claude/settings.json` |2123| `projectSettings` | `.claude/settings.json` |
2118| `userSettings` | `~/.claude/settings.json` |2124| `userSettings` | `~/.claude/settings.json` |
2119 2125
2120훅은 전달받은 `permission_suggestions` 중 하나를 그대로 자신의 `updatedPermissions` 출력으로 반환할 수 있습니다.2126훅은 전달받은 `permission_suggestions` 중 하나를 자체 `updatedPermissions` 출력으로 그대로 반환할 수 있습니다.
2121 2127
2122<h3 id="posttooluse">2128<h3 id="posttooluse">
2123 PostToolUse2129 PostToolUse
2125 2131
2126도구가 성공적으로 완료된 직후에 실행됩니다.2132도구가 성공적으로 완료된 직후에 실행됩니다.
2127 2133
2128도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.2134도구 이름으로 매칭하며, PreToolUse와 같은 값을 사용합니다.
2129 2135
2130도구 이름이 적절한 필터가 아닐 때는 더 넓게 매칭할 수 있습니다.2136도구 이름이 적절한 필터가 아닐 때는 더 넓게 매칭합니다.
2131 2137
2132* 어떤 도구든 성공적으로 완료된 후에 훅을 실행하려면 `matcher`를 생략하거나 `"*"`로 설정합니다. 그러면 훅이 무엇이 변경되었는지 직접 파악할 수 있습니다. 예를 들어 `git status --porcelain`을 실행하면 `git diff`가 놓치는 추적되지 않은 파일도 함께 나열됩니다. 실패한 도구 호출의 경우 같은 훅을 [PostToolUseFailure](#posttoolusefailure) 아래에 추가합니다.2138* 어떤 도구든 성공적으로 완료된 후에 훅을 실행하려면 `matcher`를 생략하거나 `"*"`로 설정합니다. 그러면 훅이 직접 변경 내용을 파악할 수 있습니다. 예를 들어 `git status --porcelain`을 실행하면 `git diff`가 놓치는 추적되지 않는 파일도 나열됩니다. 실패한 도구 호출에 대해서는 같은 훅을 [PostToolUseFailure](#posttoolusefailure)에 추가합니다.
2133* 무엇이 파일을 기록했는지와 관계없이 특정 파일이 디스크에서 변경될 때 훅을 실행하려면 [FileChanged](#filechanged)를 사용합니다. `Bash` 명령이나 Claude Code 외부의 프로세스가 같은 파일을 다시 쓰는 경우, Claude Code는 `Edit|Write`에 매칭되는 `PostToolUse` 훅을 실행하지 않습니다.2139* 무엇이 파일을 기록했든 특정 파일이 디스크에서 변경될 때 훅을 실행하려면 [FileChanged](#filechanged)를 사용합니다. `Bash` 명령이나 Claude Code 외부의 프로세스가 같은 파일을 다시 쓰는 경우, Claude Code는 `Edit|Write`에 매칭되는 `PostToolUse` 훅을 실행하지 않습니다.
2134 2140
2135<h4 id="posttooluse-input">2141<h4 id="posttooluse-input">
2136 PostToolUse 입력2142 PostToolUse input
2137</h4>2143</h4>
2138 2144
2139`PostToolUse` 훅은 도구가 이미 성공적으로 실행된 후에 발생합니다. 입력에는 도구에 전송된 인수인 `tool_input`과 도구가 반환한 결과인 `tool_response`가 모두 포함됩니다. 두 필드의 정확한 스키마는 도구에 따라 다릅니다. 파일 도구의 `tool_input` 경로는 [PreToolUse](#pretooluse-input)와 같은 형식으로 전달됩니다. 즉, 항상 절대 경로이며 플랫폼 고유의 구분자를 사용하므로 Windows에서는 백슬래시가 사용됩니다. MCP 도구의 경우 입력에 [`mcp_server`](#pretooluse-input) 객체도 포함됩니다.2145`PostToolUse` 훅은 도구가 이미 성공적으로 실행된 후에 발생합니다. 입력에는 도구에 전송된 인수인 `tool_input`과 도구가 반환한 결과인 `tool_response`가 모두 포함됩니다. 두 필드의 정확한 스키마는 도구에 따라 다릅니다. 파일 도구의 `tool_input` 경로는 [PreToolUse](#pretooluse-input)와 같은 형식으로 전달됩니다. 즉, 항상 절대 경로이며 플랫폼 고유의 구분자를 사용하므로 Windows에서는 백슬래시가 사용됩니다. MCP 도구의 경우 입력에 [`mcp_server`](#pretooluse-input) 객체도 포함됩니다.
2161 2167
2162| 필드 | 설명 |2168| 필드 | 설명 |
2163| :- | :- |2169| :- | :- |
2164| `duration_ms` | 선택 사항입니다. 밀리초 단위의 도구 실행 시간입니다. 권한 프롬프트와 PreToolUse 훅에서 소요된 시간은 제외됩니다 |2170| `duration_ms` | 선택 사항입니다. 밀리초 단위의 도구 실행 시간입니다. 권한 프롬프트와 PreToolUse 훅에 소요된 시간은 제외됩니다 |
2165 2171
2166<h4 id="posttooluse-decision-control">2172<h4 id="posttooluse-decision-control">
2167 PostToolUse 결정 제어2173 PostToolUse decision control
2168</h4>2174</h4>
2169 2175
2170`PostToolUse` 훅은 도구 실행 후 Claude에게 피드백을 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.2176`PostToolUse` 훅은 도구 실행 후 Claude에 피드백을 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도, 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.
2171 2177
2172| 필드 | 설명 |2178| 필드 | 설명 |
2173| :- | :- |2179| :- | :- |
2174| `decision` | `"block"`은 도구 결과 옆에 `reason`을 추가합니다. Claude는 여전히 원래 출력을 보게 되며, 출력을 대체하려면 `updatedToolOutput`을 사용합니다 |2180| `decision` | `"block"`은 도구 결과 옆에 `reason`을 추가합니다. Claude는 여전히 원래 출력을 봅니다. 출력을 대체하려면 `updatedToolOutput`을 사용합니다 |
2175| `reason` | `decision`이 `"block"`일 때 Claude에게 표시되는 설명입니다 |2181| `reason` | `decision`이 `"block"`일 때 Claude에 표시되는 설명입니다 |
2176| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2182| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. [Claude에 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
2177| `classifierContext` | Claude가 아닌 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기를 위한, 이 호출 결과에 대한 짧은 메모입니다. [자동 모드 분류기를 위한 결과 주석 달기](#annotate-a-result-for-the-auto-mode-classifier)를 참조하세요. Claude Code v2.1.236 이상이 필요합니다 |2183| `classifierContext` | Claude가 아닌 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기를 위한, 이 호출의 결과에 대한 짧은 메모입니다. [자동 모드 분류기를 위해 결과에 주석 달기](#annotate-a-result-for-the-auto-mode-classifier)를 참조하세요. Claude Code v2.1.236 이상이 필요합니다 |
2178| `updatedToolOutput` | Claude에게 전송되기 전에 도구의 출력을 제공된 값으로 대체합니다. 값은 도구의 출력 형태와 일치해야 합니다 |2184| `updatedToolOutput` | 도구의 출력이 Claude에 전송되기 전에 제공된 값으로 대체합니다. 값은 도구의 출력 형태와 일치해야 합니다 |
2179| `updatedMCPToolOutput` | [MCP 도구](#match-mcp-tools)에 대해서만 출력을 대체합니다. 모든 도구에서 작동하는 `updatedToolOutput`을 사용하는 것이 좋습니다 |2185| `updatedMCPToolOutput` | [MCP 도구](#match-mcp-tools)의 출력만 대체합니다. 모든 도구에서 작동하는 `updatedToolOutput`을 사용하는 것이 좋습니다 |
2180 2186
2181아래 예시는 `Bash` 호출의 출력을 대체합니다. 대체 값은 `Bash` 도구의 출력 형태와 일치합니다.2187아래 예시는 `Bash` 호출의 출력을 대체합니다. 대체 값은 `Bash` 도구의 출력 형태와 일치합니다.
2182 2188
2196```2202```
2197 2203
2198<Warning>2204<Warning>
2199 `updatedToolOutput`은 Claude가 보는 내용만 변경합니다. 훅이 발생할 때는 도구가 이미 실행된 상태이므로, 기록된 파일, 실행된 명령, 전송된 네트워크 요청은 이미 효과가 발생한 상태입니다. OpenTelemetry 도구 스팬 및 분석 이벤트와 같은 텔레메트리도 훅이 실행되기 전에 원래 출력을 수집합니다. 도구 호출이 실행되기 전에 이를 막거나 수정하려면 대신 [PreToolUse](#pretooluse) 훅을 사용합니다.2205 `updatedToolOutput`은 Claude가 보는 내용만 변경합니다. 훅이 발생할 때는 도구가 이미 실행된 상태이므로, 기록된 파일, 실행된 명령, 전송된 네트워크 요청은 이미 적용되었습니다. OpenTelemetry 도구 스팬이나 분석 이벤트와 같은 텔레메트리도 훅이 실행되기 전에 원래 출력을 수집합니다. 도구 호출이 실행되기 전에 이를 차단하거나 수정하려면 대신 [PreToolUse](#pretooluse) 훅을 사용합니다.
2200 2206
2201 대체 값은 도구의 출력 형태와 일치해야 합니다. 기본 제공 도구는 일반 문자열이 아닌 구조화된 객체를 반환합니다. 예를 들어 `Bash`는 `stdout`, `stderr`, `interrupted`, `isImage` 필드가 있는 객체를 반환합니다. 기본 제공 도구의 경우 도구의 출력 스키마와 일치하지 않는 값은 무시되고 원래 출력이 사용됩니다. MCP 도구 출력은 스키마 검증 없이 그대로 전달됩니다. Claude에게 필요한 오류 세부 정보를 제거하면 Claude가 잘못된 가정에 따라 작업을 진행할 수 있습니다.2207 대체 값은 도구의 출력 형태와 일치해야 합니다. 기본 제공 도구는 일반 문자열이 아닌 구조화된 객체를 반환합니다. 예를 들어 `Bash`는 `stdout`, `stderr`, `interrupted`, `isImage` 필드가 있는 객체를 반환합니다. 기본 제공 도구의 경우 도구의 출력 스키마와 일치하지 않는 값은 무시되고 원래 출력이 사용됩니다. MCP 도구 출력은 스키마 검증 없이 그대로 전달됩니다. Claude에 필요한 오류 세부 정보를 제거하면 Claude가 잘못된 가정에 따라 작업을 진행할 수 있습니다.
2202</Warning>2208</Warning>
2203 2209
2204<h4 id="annotate-a-result-for-the-auto-mode-classifier">2210<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2205 자동 모드 분류기를 위한 결과 주석 달기2211 Annotate a result for the auto mode classifier
2206</h4>2212</h4>
2207 2213
2208`classifierContext`를 반환하면 도구 호출 결과에 대한 짧은 메모를 Claude가 아닌 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기에 전송합니다. 분류기는 [도구 결과 자체를 전달받지 않으므로](/docs/ko/permission-modes#how-the-classifier-evaluates-actions), 이 필드는 분류기가 이후 작업을 검토하기 전에 호출이 반환한 내용에 대해 알려 줄 수 있는 공식적인 방법입니다. 이 필드는 Claude Code v2.1.236 이상이 필요합니다.2214`classifierContext`를 반환하면 도구 호출 결과에 대한 짧은 메모를 Claude가 아닌 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기에 보낼 수 있습니다. 분류기는 [도구 결과 자체를 전달받지 않으므로](/docs/ko/permission-modes#how-the-classifier-evaluates-actions), 이 필드는 분류기가 이후 작업을 검토하기 전에 호출이 반환한 내용에 대해 알려 주는 공식적인 방법입니다. 이 필드에는 Claude Code v2.1.236 이상이 필요합니다.
2209 2215
2210아래 예시는 쿼리 출력의 출처를 분류기에 알려 줍니다.2216아래 예시는 쿼리 출력의 출처를 분류기에 알려 줍니다.
2211 2217
2218}2224}
2219```2225```
2220 2226
2221분류기가 메모에 부여하는 가중치는 훅을 어디에서 구성했는지에 따라 달라집니다.2227분류기가 메모에 부여하는 비중은 훅을 구성한 위치에 따라 달라집니다.
2222 2228
2223* **Claude Code에서 구성한 훅**: 설정 파일, 플러그인, 스킬, 에이전트 frontmatter에서 온 훅의 경우, 분류기는 메모를 검증되지 않은 애플리케이션 제공 컨텍스트로 취급합니다. 메모는 사용자 의도를 확립하지 않으며, 메모에서 사용자가 무언가를 승인하거나 요청했다고 주장하는 경우 분류기는 대화에 있는 사용자의 실제 메시지와 대조하여 그 주장을 확인합니다2229* **Claude Code에서 구성된 훅**: 설정 파일, 플러그인, 스킬, 에이전트 frontmatter의 훅에 대해 분류기는 메모를 검증되지 않은, 애플리케이션이 제공한 컨텍스트로 취급합니다. 메모는 사용자 의도를 확립하지 않으며, 메모가 사용자가 무언가를 승인했거나 요청했다고 주장하면 분류기는 그 주장을 대화 속 사용자의 실제 메시지와 대조합니다
2224* **프로세스 내 Agent SDK 콜백**: Claude Code를 내장한 애플리케이션이 훅을 [TypeScript SDK 콜백](/docs/ko/agent-sdk/hooks)으로 등록하고 실행 중인 세션에서 메모를 반환하는 경우, 분류기는 메모에 전달된 사용자 발언을 사용자 의도로 고려할 수 있습니다. 이러한 발언은 분류기가 사용자가 보낸 메시지로부터 수용할 수 있는 동의 요건을 충족할 수 있지만, 사용자 자신의 메시지로도 해제할 수 없는 차단을 해제하지는 않습니다. 세션이 재개된 후에는 Claude Code가 복원된 메모를 검증되지 않은 컨텍스트로 취급합니다. 두 그룹의 훅이 같은 호출에 주석을 다는 경우, 분류기는 결합된 메모를 검증되지 않은 것으로 취급합니다2230* **프로세스 내 Agent SDK 콜백**: Claude Code를 내장한 애플리케이션이 훅을 [TypeScript SDK 콜백](/docs/ko/agent-sdk/hooks)으로 등록하고 라이브 세션 중에 메모를 반환하면, 분류기는 메모에 전달된 사용자 진술을 사용자 의도로 고려할 수 있습니다. 이러한 진술은 분류기가 사용자가 보낸 메시지로부터 받아들일 동의 요건을 충족할 수 있지만, 사용자 자신의 메시지로도 해제할 수 없는 차단을 해제하지는 못합니다. 세션이 재개된 후에는 Claude Code가 복원된 메모를 검증되지 않은 컨텍스트로 취급합니다. 두 그룹의 훅이 같은 호출에 주석을 달면 분류기는 결합된 메모를 검증되지 않은 것으로 취급합니다
2225 2231
2226Claude Code는 메모를 전달할 때 다음과 같은 제한을 적용합니다.2232Claude Code는 메모를 전달할 때 다음 제한을 적용합니다.
2227 2233
2228* **길이**: Claude Code는 하나의 도구 호출에 대한 메모를 2,000자로 제한하고 나머지는 잘라냅니다. 이 제한은 해당 호출에 응답하는 모든 훅이 공유합니다2234* **길이**: Claude Code는 하나의 도구 호출에 대한 메모를 2,000자로 제한하고 나머지는 잘라 냅니다. 이 한도는 해당 호출에 응답하는 모든 훅이 공유합니다
2229* **동기 응답만 해당**: [백그라운드에서 실행되는](#run-hooks-in-the-background) 훅의 응답은 Claude Code가 도구 결과를 기록한 후에 도착하므로, Claude Code는 이러한 응답의 필드를 무시합니다2235* **동기 응답만 해당**: [백그라운드에서 실행되는](#run-hooks-in-the-background) 훅의 응답에 있는 이 필드는 무시됩니다. 해당 응답은 Claude Code가 도구 결과를 기록한 후에 도착하기 때문입니다
2230* **분류기가 기록하지 않는 호출**: 분류기의 트랜스크립트는 파일 읽기 및 검색과 같은 읽기 전용 조회를 생략합니다. Claude Code는 이러한 호출에 첨부된 메모를 삭제합니다2236* **분류기가 기록하지 않는 호출**: 분류기의 트랜스크립트에는 파일 읽기나 검색 같은 읽기 전용 조회가 포함되지 않습니다. Claude Code는 이러한 호출에 첨부된 메모를 삭제합니다
2231* **재작성과의 상호작용**: 메모가 `updatedToolOutput`으로 대체하는 출력을 설명하는 경우, 같은 훅 응답에서 두 필드를 모두 반환합니다. 해당 재작성이 거부되거나 다른 훅의 재작성이 이를 대체하면 Claude Code는 메모를 삭제합니다. 재작성 없이 반환한 메모는 다른 훅이 출력을 재작성하더라도 Claude Code가 전달합니다2237* **재작성과의 상호작용**: 메모가 `updatedToolOutput`으로 대체하는 출력을 설명하는 경우, 같은 훅 응답에서 두 필드를 모두 반환합니다. 해당 재작성이 거부되거나 다른 훅의 재작성이 이를 대체하면 Claude Code는 메모를 삭제합니다. 재작성 없이 반환한 메모는 다른 훅이 출력을 재작성하더라도 Claude Code가 전달합니다
2232 2238
2233<Warning>2239<Warning>
2234 분류기는 `classifierContext`에 넣은 내용을 세션을 호스팅하는 애플리케이션이 제공한 정보로 읽으므로, 신뢰할 수 없는 도구 출력이나 제3자 텍스트를 이 필드에 복사하지 마세요. 메모는 출처에 대한 사실이나 해당 호출에 대한 사용자 발언처럼 이 호출 하나에 대한 짧은 주장으로 유지하고, 관련 없는 메시지나 일련의 이벤트를 전달하는 데 이 필드를 사용하지 마세요.2240 분류기는 `classifierContext`에 넣은 내용을 세션을 호스팅하는 애플리케이션의 정보로 읽으므로, 신뢰할 수 없는 도구 출력이나 서드파티 텍스트를 여기에 복사하지 마세요. 메모는 출처에 관한 사실이나 이에 대한 사용자 진술처럼 해당 호출 하나에 대한 짧은 주장으로 유지하고, 관련 없는 메시지나 일련의 이벤트를 전달하는 데 이 필드를 사용하지 마세요.
2235</Warning>2241</Warning>
2236 2242
2237<h3 id="posttoolusefailure">2243<h3 id="posttoolusefailure">
2238 PostToolUseFailure2244 PostToolUseFailure
2239</h3>2245</h3>
2240 2246
2241실행을 시작한 도구가 실패할 때 실행됩니다. 즉, 도구에서 오류가 발생했거나 MCP 도구가 오류 결과를 반환한 경우입니다. 실패를 로그에 기록하거나, 알림을 보내거나, Claude에게 수정 피드백을 제공하는 데 사용합니다.2247실행을 시작한 도구가 실패할 때 실행됩니다. 즉, 도구가 오류를 발생시켰거나 MCP 도구가 오류 결과를 반환한 경우입니다. 실패를 로그에 기록하거나, 알림을 보내거나, Claude에 수정 피드백을 제공하는 데 사용합니다.
2242 2248
2243도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.2249도구 이름으로 매칭하며, PreToolUse와 같은 값을 사용합니다.
2244 2250
2245<Note>2251<Note>
2246 이 이벤트는 실행 전에 거부된 도구 호출에서는 발생하지 않습니다. 여기에는 알 수 없는 도구 이름, 스키마 또는 도구별 검증에 실패한 입력, 권한 거부가 해당합니다. 검증 거부는 `tool_use_error` 결과로 반환되며 훅이 실행되기 전에 발생하므로 `PreToolUse`와 `PostToolUseFailure` 모두 발생하지 않습니다. 권한 거부는 `PreToolUse`를 발생시키지만 이 이벤트는 발생시키지 않습니다. [PermissionDenied](#permissiondenied)를 참조하세요.2252 이 이벤트는 실행 전에 거부된 도구 호출에 대해서는 발생하지 않습니다. 알 수 없는 도구 이름, 스키마 또는 도구별 검증에 실패한 입력, 권한 거부가 여기에 해당합니다. 검증 거부는 `tool_use_error` 결과로 반환되며 훅이 실행되기 전에 발생하므로, `PreToolUse`와 `PostToolUseFailure` 모두 발생하지 않습니다. 권한 거부는 `PreToolUse`를 발생시키지만 이 이벤트는 발생시키지 않습니다. [PermissionDenied](#permissiondenied)를 참조하세요.
2247</Note>2253</Note>
2248 2254
2249<h4 id="posttoolusefailure-input">2255<h4 id="posttoolusefailure-input">
2250 PostToolUseFailure 입력2256 PostToolUseFailure input
2251</h4>2257</h4>
2252 2258
2253PostToolUseFailure 훅은 PostToolUse와 같은 `tool_name` 및 `tool_input` 필드와 함께 최상위 필드로 오류 정보를 전달받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 전달받습니다. 예를 들어 실패한 `npm test` 명령은 다음을 전달할 수 있습니다.2259PostToolUseFailure 훅은 PostToolUse와 같은 `tool_name` 및 `tool_input` 필드를 전달받으며, 오류 정보는 최상위 필드로 함께 전달받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 전달받습니다. 예를 들어 실패한 `npm test` 명령은 다음을 전달할 수 있습니다.
2254 2260
2255```json theme={null}2261```json theme={null}
2256{2262{
2274| 필드 | 설명 |2280| 필드 | 설명 |
2275| :- | :- |2281| :- | :- |
2276| `error` | 무엇이 잘못되었는지 설명하는 문자열입니다. 형식은 실패한 도구에 따라 다릅니다 |2282| `error` | 무엇이 잘못되었는지 설명하는 문자열입니다. 형식은 실패한 도구에 따라 다릅니다 |
2277| `is_interrupt` | 선택적 boolean입니다. 실패가 도구가 보고한 오류가 아니라 중단(abort)으로 Claude Code에 도달한 경우 true입니다. 실행 중인 도구를 취소하는 경우에는 이 훅이 발생하지 않으며, 대신 도구 결과에 중단 메시지가 포함됩니다 |2283| `is_interrupt` | 선택적 불리언입니다. 실패가 도구가 보고한 오류가 아닌 중단(abort)으로 Claude Code에 도달한 경우 true입니다. 실행 중인 도구를 취소해도 이 훅은 발생하지 않으며, 대신 도구 결과에 중단 메시지가 포함됩니다 |
2278| `duration_ms` | 선택 사항입니다. 밀리초 단위의 도구 실행 시간입니다. 권한 프롬프트와 PreToolUse 훅에서 소요된 시간은 제외됩니다 |2284| `duration_ms` | 선택 사항입니다. 밀리초 단위의 도구 실행 시간입니다. 권한 프롬프트와 PreToolUse 훅에 소요된 시간은 제외됩니다 |
2279 2285
2280`error` 문자열은 일반적으로 Claude가 실패한 도구의 결과로 받는 텍스트와 같습니다. 형식은 도구와 실패 유형에 따라 다릅니다. 훅은 `tool_name`, `is_interrupt`, 첫 줄의 `Exit code N`을 기준으로 동작하도록 작성하고, 문자열의 나머지 부분은 안정적인 형식이 아닌 표시용 텍스트로 취급합니다.2286`error` 문자열은 일반적으로 Claude가 실패한 도구의 결과로 받는 텍스트와 같습니다. 형식은 도구와 실패 유형에 따라 다릅니다. 훅은 `tool_name`, `is_interrupt`, 그리고 첫 줄의 `Exit code N`을 기준으로 판단하고, 문자열의 나머지 부분은 안정적인 형식이 아닌 표시용 텍스트로 취급합니다.
2281 2287
2282* Bash와 PowerShell의 경우, 실행된 후 종료된 명령은 첫 줄에 `Exit code N`을 생성하고, 그 뒤에 명령이 생성한 출력을 stdout과 stderr가 섞인 하나의 블록으로 생성합니다2288* Bash와 PowerShell의 경우, 실행 후 종료된 명령은 첫 줄에 `Exit code N`을 생성하고, 이어서 명령이 생성한 출력을 stdout과 stderr가 섞인 하나의 블록으로 생성합니다
2283* Claude Code가 셸 프로세스 자체를 시작할 수 없었던 경우, 페이로드에 종료 코드 줄 없이 실패 메시지만 포함될 수도 있습니다2289* Claude Code가 셸 프로세스 자체를 시작할 수 없었던 경우, 페이로드에 종료 코드 줄 없이 실패 메시지만 포함될 수도 있습니다
2284* Claude Code는 긴 문자열의 중간 부분을 `... [N characters truncated] ...` 마커를 기준으로 잘라내며, `Command timed out after 2m 0s`와 같은 자체 줄을 삽입할 수 있습니다2290* Claude Code는 긴 문자열의 가운데를 `... [N characters truncated] ...` 마커를 기준으로 잘라 내며, `Command timed out after 2m 0s`와 같은 자체 줄을 삽입할 수 있습니다
2285 2291
2286<h4 id="posttoolusefailure-decision-control">2292<h4 id="posttoolusefailure-decision-control">
2287 PostToolUseFailure 결정 제어2293 PostToolUseFailure decision control
2288</h4>2294</h4>
2289 2295
2290`PostToolUseFailure` 훅은 도구 실패 후 Claude에게 컨텍스트를 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.2296`PostToolUseFailure` 훅은 도구 실패 후 Claude에 컨텍스트를 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도, 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.
2291 2297
2292| 필드 | 설명 |2298| 필드 | 설명 |
2293| :- | :- |2299| :- | :- |
2294| `additionalContext` | 오류와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2300| `additionalContext` | 오류와 함께 Claude의 컨텍스트에 추가되는 문자열입니다. [Claude에 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
2295 2301
2296```json theme={null}2302```json theme={null}
2297{2303{
2306 PostToolBatch2312 PostToolBatch
2307</h3>2313</h3>
2308 2314
2309배치의 모든 도구 호출이 처리된 후, Claude Code가 모델에 다음 요청을 보내기 전에 한 번 실행됩니다. `PostToolUse`는 도구마다 한 번씩 발생하므로, Claude가 병렬 도구 호출을 수행하면 동시에 발생합니다. `PostToolBatch`는 전체 배치에 대해 정확히 한 번 발생하므로, 단일 도구가 아닌 실행된 도구 집합에 따라 달라지는 컨텍스트를 주입하기에 적합한 위치입니다. 이 이벤트에는 matcher가 없습니다.2315배치의 모든 도구 호출이 처리된 후, Claude Code가 모델에 다음 요청을 보내기 전에 한 번 실행됩니다. `PostToolUse`는 도구마다 한 번씩 발생하므로, Claude가 병렬 도구 호출을 하면 동시에 발생합니다. `PostToolBatch`는 전체 배치에 대해 정확히 한 번 발생하므로, 단일 도구가 아닌 실행된 도구 집합에 따라 달라지는 컨텍스트를 주입하기에 적합합니다. 이 이벤트에는 matcher가 없습니다.
2310 2316
2311<h4 id="posttoolbatch-input">2317<h4 id="posttoolbatch-input">
2312 PostToolBatch 입력2318 PostToolBatch input
2313</h4>2319</h4>
2314 2320
2315[공통 입력 필드](#common-input-fields) 외에도 PostToolBatch 훅은 배치의 모든 도구 호출을 설명하는 배열인 `tool_calls`를 전달받습니다.2321[공통 입력 필드](#common-input-fields) 외에도, PostToolBatch 훅은 배치의 모든 도구 호출을 설명하는 배열인 `tool_calls`를 전달받습니다.
2316 2322
2317```json theme={null}2323```json theme={null}
2318{2324{
2338}2344}
2339```2345```
2340 2346
2341`tool_response`에는 모델이 해당 `tool_result` 블록에서 받는 것과 같은 내용이 포함됩니다. 값은 도구가 내보낸 그대로의 직렬화된 문자열 또는 콘텐츠 블록 배열입니다. `Read`의 경우 원시 파일 내용이 아니라 줄 번호가 앞에 붙은 텍스트입니다. 응답이 클 수 있으므로 필요한 필드만 파싱합니다.2347`tool_response`에는 모델이 해당 `tool_result` 블록에서 받는 것과 같은 내용이 포함됩니다. 값은 도구가 내보낸 그대로의 직렬화된 문자열 또는 콘텐츠 블록 배열입니다. `Read`의 경우 원시 파일 내용이 아니라 줄 번호가 앞에 붙은 텍스트를 의미합니다. 응답이 클 수 있으므로 필요한 필드만 파싱합니다.
2342 2348
2343<Note>2349<Note>
2344 `tool_response`의 형태는 `PostToolUse`의 형태와 다릅니다. `PostToolUse`는 도구의 구조화된 `Output` 객체(예: `Write`의 경우 `{filePath: "...", type: "create"}`)를 전달하고, `PostToolBatch`는 모델이 보는 직렬화된 `tool_result` 콘텐츠를 전달합니다.2350 `tool_response`의 형태는 `PostToolUse`의 것과 다릅니다. `PostToolUse`는 `Write`의 `{filePath: "...", type: "create"}`와 같은 도구의 구조화된 `Output` 객체를 전달하고, `PostToolBatch`는 모델이 보는 직렬화된 `tool_result` 내용을 전달합니다.
2345</Note>2351</Note>
2346 2352
2347<h4 id="posttoolbatch-decision-control">2353<h4 id="posttoolbatch-decision-control">
2348 PostToolBatch 결정 제어2354 PostToolBatch decision control
2349</h4>2355</h4>
2350 2356
2351`PostToolBatch` 훅은 Claude를 위한 컨텍스트를 주입할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.2357`PostToolBatch` 훅은 Claude를 위한 컨텍스트를 주입할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도, 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.
2352 2358
2353| 필드 | 설명 |2359| 필드 | 설명 |
2354| :- | :- |2360| :- | :- |
2355| `additionalContext` | 다음 모델 호출 전에 한 번 주입되는 컨텍스트 문자열입니다. 전달 방식, 포함할 내용, 재개된 세션에서 이전 값을 처리하는 방식은 [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2361| `additionalContext` | 다음 모델 호출 전에 한 번 주입되는 컨텍스트 문자열입니다. 전달 세부 사항, 포함할 내용, 재개된 세션이 이전 값을 처리하는 방식은 [Claude에 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
2356 2362
2357```json theme={null}2363```json theme={null}
2358{2364{
2363}2369}
2364```2370```
2365 2371
2366`decision: "block"` 또는 `continue: false`를 반환하면 다음 모델 호출 전에 에이전틱 루프가 중지됩니다. 차단 메시지는 JSON의 `reason` 또는 `stopReason`에서 가져오거나, 종료 코드 2인 경우 stderr에서 가져옵니다. 이 메시지는 트랜스크립트에 경고로 표시되며 대화에 남아 있으므로, 대화가 계속되면 Claude가 이를 보게 됩니다.2372`decision: "block"` 또는 `continue: false`를 반환하면 다음 모델 호출 전에 에이전틱 루프가 중지됩니다. 차단 메시지는 JSON의 `reason` 또는 `stopReason`에서, 또는 종료 코드 2의 경우 stderr에서 가져옵니다. 이 메시지는 트랜스크립트에 경고로 표시되며 대화에 남아 있으므로, 대화가 계속되면 Claude가 이를 보게 됩니다.
2367 2373
2368<h3 id="permissiondenied">2374<h3 id="permissiondenied">
2369 PermissionDenied2375 PermissionDenied
2370</h3>2376</h3>
2371 2377
2372[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)가 도구 호출을 거부할 때 실행됩니다. 여기에는 [자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부했거나](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) 분류기의 응답을 파싱할 수 없어서 분류기 판정 없이 거부한 경우도 포함됩니다. 이 훅은 자동 모드에서만 발생합니다. 사용자가 권한 대화 상자에서 직접 거부하거나, `PreToolUse` 훅이 호출을 차단하거나, `deny` 규칙이 매칭되는 경우에는 실행되지 않습니다. 거부를 로그에 기록하거나, 구성을 조정하거나, 모델에게 도구 호출을 재시도해도 된다고 알리는 데 사용합니다.2378[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)가 도구 호출을 거부할 때 실행됩니다. [자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action)했거나 분류기의 응답을 파싱할 수 없어서 분류기 판정 없이 거부하는 경우도 포함됩니다. 이 훅은 자동 모드에서만 발생합니다. 사용자가 권한 대화 상자를 수동으로 거부하거나, `PreToolUse` 훅이 호출을 차단하거나, `deny` 규칙이 매칭되는 경우에는 실행되지 않습니다. 거부를 로그에 기록하거나, 구성을 조정하거나, 모델에 도구 호출을 재시도해도 된다고 알리는 데 사용합니다.
2373 2379
2374도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.2380도구 이름으로 매칭하며, PreToolUse와 같은 값을 사용합니다.
2375 2381
2376<h4 id="permissiondenied-input">2382<h4 id="permissiondenied-input">
2377 PermissionDenied 입력2383 PermissionDenied input
2378</h4>2384</h4>
2379 2385
2380[공통 입력 필드](#common-input-fields) 외에도 PermissionDenied 훅은 `tool_name`, `tool_input`, `tool_use_id`, `reason`을 전달받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 전달받습니다.2386[공통 입력 필드](#common-input-fields) 외에도, PermissionDenied 훅은 `tool_name`, `tool_input`, `tool_use_id`, `reason`을 전달받습니다. MCP 도구의 경우 [`mcp_server`](#pretooluse-input) 객체도 전달받습니다.
2381 2387
2382```json theme={null}2388```json theme={null}
2383{2389{
2398 2404
2399| 필드 | 설명 |2405| 필드 | 설명 |
2400| :- | :- |2406| :- | :- |
2401| `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`입니다 |
2402 2408
2403<h4 id="permissiondenied-decision-control">2409<h4 id="permissiondenied-decision-control">
2404 PermissionDenied 결정 제어2410 PermissionDenied decision control
2405</h4>2411</h4>
2406 2412
2407PermissionDenied 훅은 모델에게 거부된 도구 호출을 재시도해도 된다고 알릴 수 있습니다. `hookSpecificOutput.retry`를 `true`로 설정한 JSON 객체를 반환합니다.2413PermissionDenied 훅은 거부된 도구 호출을 모델이 재시도해도 된다고 알릴 수 있습니다. `hookSpecificOutput.retry`를 `true`로 설정한 JSON 객체를 반환합니다.
2408 2414
2409```json theme={null}2415```json theme={null}
2410{2416{
2415}2421}
2416```2422```
2417 2423
2418`retry`가 `true`이면 Claude Code는 모델에게 도구 호출을 재시도해도 된다고 알리는 메시지를 대화에 추가합니다. Claude Code가 거부 자체를 번복하지는 않습니다. 훅이 JSON을 반환하지 않거나 `retry: false`를 반환하면 거부가 유지되고 모델은 원래의 거부 메시지를 받습니다.2424`retry`가 `true`이면 Claude Code는 모델에 도구 호출을 재시도해도 된다고 알리는 메시지를 대화에 추가합니다. Claude Code가 거부 자체를 취소하지는 않습니다. 훅이 JSON을 반환하지 않거나 `retry: false`를 반환하면 거부가 유지되고 모델은 원래의 거부 메시지를 받습니다.
2419 2425
2420분류기가 [작업에 대한 판정을 내리지 못한](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) 경우, 즉 분류기의 응답을 파싱할 수 없었거나 자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부한 경우 Claude Code는 `retry: true`를 무시합니다. 이러한 거부의 경우 Claude Code는 이미 거부 메시지에서 모델에게 나중에 재시도할지 다음으로 넘어갈지 알려 줍니다.2426분류기가 [해당 작업에 대해 판정을 내리지 못한](/docs/ko/errors#auto-mode-cannot-determine-the-safety-of-an-action) 경우, 즉 응답을 파싱할 수 없었거나 자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부한 경우에는 Claude Code가 `retry: true`를 무시합니다. 이러한 거부에 대해서는 Claude Code가 이미 거부 메시지에서 나중에 재시도할지 아니면 다른 작업으로 넘어갈지를 모델에 알려 줍니다.
2421 2427
2422<h3 id="notification">2428<h3 id="notification">
2423 Notification2429 Notification
2425 2431
2426Claude Code가 알림을 보낼 때 실행됩니다. 알림 유형으로 매칭합니다. 모든 알림 유형에 대해 훅을 실행하려면 matcher를 생략합니다.2432Claude Code가 알림을 보낼 때 실행됩니다. 알림 유형으로 매칭합니다. 모든 알림 유형에 대해 훅을 실행하려면 matcher를 생략합니다.
2427 2433
2428데스크톱 알림을 꺼 두어도 이 훅 이벤트는 전달됩니다. `notifications_disabled`를 포함한 `preferredNotifChannel` 설정은 사용자에게 알리는 방식만 변경할 뿐 훅의 실행 여부에는 영향을 주지 않습니다.2434데스크톱 알림을 꺼 두어도 이러한 훅 이벤트는 전달됩니다. `notifications_disabled`를 포함한 `preferredNotifChannel` 설정은 사용자에게 알리는 방식만 바꿀 뿐, 훅 실행 여부에는 영향을 주지 않습니다.
2429 2435
2430| Matcher | 발생 시점 |2436| Matcher | 발생 시점 |
2431| :- | :- |2437| :- | :- |
2432| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 처리된 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대한 사용자 승인을 필요로 하고, 프롬프트가 약 6초 동안 대기한 경우 |2438| `permission_prompt` | Claude가 도구 사용 또는 샌드박스 처리된 명령의 [네트워크 요청](/docs/ko/sandboxing#network-isolation)에 대한 사용자 승인을 필요로 하며, 프롬프트가 약 6초 동안 대기한 경우 |
2433| `idle_prompt` | Claude가 약 60초 전에 응답을 마쳤고 그 이후 사용자가 입력하지 않은 경우 |2439| `idle_prompt` | Claude가 약 60초 전에 응답을 마쳤고 그 이후 사용자가 입력하지 않은 경우 |
2434| `auth_success` | 인증이 완료된 경우 |2440| `auth_success` | 인증이 완료된 경우 |
2435| `elicitation_dialog` | MCP 서버가 elicitation 양식을 열었고 사용자가 약 6초 동안 입력하지 않은 경우 |2441| `elicitation_dialog` | MCP 서버가 elicitation 양식을 열었고 사용자가 약 6초 동안 입력하지 않은 경우 |
2436| `elicitation_url_dialog` | MCP 서버가 브라우저 URL을 열도록 요청했고 사용자가 약 6초 동안 입력하지 않은 경우 |2442| `elicitation_url_dialog` | MCP 서버가 브라우저 URL을 열도록 요청했고 사용자가 약 6초 동안 입력하지 않은 경우 |
2437| `elicitation_complete` | MCP 서버가 [URL 모드 elicitation](#elicitation-input)이 완료되었다고 보고한 경우 |2443| `elicitation_complete` | MCP 서버가 [URL 모드 elicitation](#elicitation-input)이 완료되었다고 보고한 경우 |
2438| `elicitation_response` | MCP elicitation 응답이 서버로 다시 전송된 경우 |2444| `elicitation_response` | MCP elicitation 응답이 서버로 다시 전송된 경우 |
2439| `agent_needs_input` | 터미널에서 [에이전트 뷰](/docs/ko/agent-view)가 열려 있는 동안 백그라운드 세션이 사용자 입력을 기다리기 시작한 경우. 터미널 세션에서 [에이전트 팀 팀원의 터미널 설정 질문](/docs/ko/agent-teams#choose-a-display-mode)이나 [분류기 요청 요금](/docs/ko/auto-mode-classifier-billing)에 대한 자동 모드 안내를 표시하고 사용자가 약 6초 동안 입력하지 않은 경우에도 발생합니다 |2445| `agent_needs_input` | 터미널에서 [에이전트 뷰](/docs/ko/agent-view)가 열려 있는 동안 백그라운드 세션이 사용자 입력을 기다리기 시작한 경우. 터미널 세션이 [에이전트 팀 팀원의 터미널 설정 질문](/docs/ko/agent-teams#choose-a-display-mode)이나 [분류기 요청 요금](/docs/ko/auto-mode-classifier-billing)에 대한 자동 모드 안내를 표시했고 사용자가 약 6초 동안 입력하지 않은 경우에도 발생합니다 |
2440| `agent_completed` | 백그라운드 세션이 완료되거나 실패한 경우. 터미널에서 [에이전트 뷰](/docs/ko/agent-view)가 열려 있는 동안에만 발생합니다 |2446| `agent_completed` | 백그라운드 세션이 완료되거나 실패한 경우. 터미널에서 [에이전트 뷰](/docs/ko/agent-view)가 열려 있을 때만 발생합니다 |
2441| `quota_auto_resume_fired` | claude.ai 사용 한도로 일시 중지된 작업을 Claude Code가 계속 진행하는 경우. 한도가 재설정될 때 진행하거나, 대기 중에 Claude Code에서 사용량 크레딧 추가, 플랜 업그레이드, 모델 전환 등의 작업으로 사용량을 다시 사용할 수 있게 되면 더 일찍 진행합니다. 단, [모델 설정 예외](/docs/ko/interactive-mode#wait-for-a-usage-limit-to-reset)가 적용됩니다 |2447| `quota_auto_resume_fired` | claude.ai 사용 한도로 일시 중지된 작업을 Claude Code가 계속하는 경우. 한도가 재설정될 때, 또는 대기 중에 사용량 크레딧 추가, 플랜 업그레이드, 모델 전환처럼 Claude Code에서 수행한 작업으로 사용량을 다시 사용할 수 있게 되면 더 일찍 계속하며, [모델 설정 예외](/docs/ko/interactive-mode#wait-for-a-usage-limit-to-reset)가 적용됩니다 |
2442| `quota_auto_resume_stale` | 컴퓨터가 약 30분 이상 절전 상태인 동안 claude.ai 사용 한도가 재설정된 경우. Claude Code는 계속 진행하지 않고 사용자가 `Enter`를 누를 때까지 기다립니다. 절전 시간이 더 짧으면 계속 진행하고 대신 `quota_auto_resume_fired`를 발생시킵니다 |2448| `quota_auto_resume_stale` | 컴퓨터가 약 30분 이상 절전 상태인 동안 claude.ai 사용 한도가 재설정된 경우. Claude Code는 계속하지 않고 사용자가 `Enter`를 누를 때까지 기다립니다. 더 짧게 절전한 후에는 계속 진행하며 대신 `quota_auto_resume_fired`를 발생시킵니다 |
2443| `quota_auto_resume_disabled` | Claude Code가 작업을 계속하지 않고 claude.ai 사용 한도 대기를 종료하는 경우. 즉, Claude Code가 스스로 시작한 대기 중에 [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit)이 꺼졌거나 재설정 시점이 24시간 이상 뒤로 밀린 경우, 계속 진행한 작업이 계속 한도에 도달한 경우, 또는 계속 진행이 모델에 도달하기 전에 차단된 경우입니다. 사용자가 `Esc` 또는 `Ctrl+C`를 누르거나 **Don't continue automatically**를 선택한 경우에는 발생하지 않습니다 |2449| `quota_auto_resume_disabled` | Claude Code가 작업을 계속하지 않고 claude.ai 사용 한도 대기를 종료한 경우. [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit)이 꺼졌거나, Claude Code가 스스로 시작한 대기 중에 재설정 시각이 24시간 이상 뒤로 밀렸거나, 계속된 작업이 반복해서 한도에 도달했거나, 계속 진행이 모델에 도달하기 전에 차단된 경우입니다. 사용자가 `Esc` 또는 `Ctrl+C`를 누르거나 **Don't continue automatically**를 선택한 경우에는 발생하지 않습니다 |
2444 2450
2445`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` 유형은 Claude Code v2.1.234 이상이 필요합니다.2451`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` 유형에는 Claude Code v2.1.234 이상이 필요합니다.
2446 2452
2447터미널 세션에서 샌드박스 처리된 명령의 네트워크 요청에 대한 `permission_prompt`는 Claude Code v2.1.246 이상이 필요합니다.2453터미널 세션에서 샌드박스 처리된 명령의 네트워크 요청에 대한 `permission_prompt`에는 Claude Code v2.1.246 이상이 필요합니다.
2448 2454
2449팀원의 터미널 설정 질문에 대한 `agent_needs_input`은 Claude Code v2.1.248 이상이 필요합니다.2455팀원의 터미널 설정 질문에 대한 `agent_needs_input`에는 Claude Code v2.1.248 이상이 필요합니다.
2450 2456
2451<Note>2457<Note>
2452 `permission_prompt`, `idle_prompt`, `elicitation_dialog`, `elicitation_url_dialog` 유형은 데스크톱 알림과 타이밍을 공유하므로, 터미널 세션에서는 사용자가 터미널에서 자리를 비운 것으로 보일 때만 표시됩니다.2458 `permission_prompt`, `idle_prompt`, `elicitation_dialog`, `elicitation_url_dialog` 유형은 데스크톱 알림과 타이밍을 공유하므로, 터미널 세션에서는 사용자가 터미널을 떠나 있는 것으로 보일 때만 표시됩니다.
2453 2459
2454 * `permission_prompt`는 사용자가 약 6초 동안 입력하지 않으면 발생합니다. 타이머는 권한 프롬프트가 나타날 때 시작되며, 키를 입력할 때마다 연기됩니다. Claude가 도구 사용 권한을 요청할 때 즉시 훅을 실행하려면 대신 [PermissionRequest](#permissionrequest)를 사용합니다.2460 * `permission_prompt`는 사용자가 약 6초 동안 입력하지 않으면 발생합니다. 타이머는 권한 프롬프트가 나타날 때 시작되며, 키를 누를 때마다 지연됩니다. Claude가 도구 사용 권한을 요청할 때 즉시 훅을 실행하려면 대신 [PermissionRequest](#permissionrequest)를 사용합니다.
2455 * `idle_prompt`는 Claude가 응답을 마친 후 약 60초가 지나면 발생하며, 그 이후 사용자가 입력하지 않은 경우에만 발생합니다. Claude Code는 claude.ai 사용 한도가 재설정되기를 기다리는 동안에는 `idle_prompt`를 보내지 않습니다. 대기가 자체적으로 종료되면 대신 `quota_auto_resume_*` 유형 중 하나가 발생합니다.2461 * `idle_prompt`는 Claude가 응답을 마친 후 약 60초 뒤에 발생하며, 그 이후 사용자가 입력하지 않았고 백그라운드 [서브에이전트](/docs/ko/sub-agents) 같은 백그라운드 에이전트가 실행 중이지 않은 경우에만 발생합니다. Claude Code는 claude.ai 사용 한도가 재설정되기를 기다리는 동안에는 `idle_prompt`를 보내지 않습니다. 대기가 자체적으로 끝나면 대신 `quota_auto_resume_*` 유형 중 하나가 발생합니다.
2456 * elicitation 양식의 경우 `elicitation_dialog`, 브라우저 URL 요청의 경우 `elicitation_url_dialog`가 사용자가 약 6초 동안 입력하지 않으면 발생합니다. 둘 다 `permission_prompt`와 같은 6초 기준을 공유합니다. 타이머는 대화 상자가 나타날 때 시작되며, 키를 입력할 때마다 연기됩니다.2462 * elicitation 양식에 대한 `elicitation_dialog` 또는 브라우저 URL 요청에 대한 `elicitation_url_dialog`는 사용자가 약 6초 동안 입력하지 않으면 발생합니다. 둘 다 `permission_prompt`와 같은 6초 조건을 공유합니다. 타이머는 대화 상자가 나타날 때 시작되며, 키를 누를 때마다 지연됩니다.
2457 2463
2458 다른 대화 상자가 화면에 있는 동안 도착한 권한 요청이나 elicitation도 같은 6초 기준을 유지하며, 요청이 도착한 시점부터 시간을 잽니다. 요청이 아직 열린 대화 상자 뒤에서 대기하는 동안에도 알림이 전달될 수 있습니다.2464 다른 대화 상자가 화면에 있는 동안 도착한 권한 요청이나 elicitation도 요청이 도착한 시점부터 계산되는 같은 6초 조건을 유지합니다. 요청이 아직 열린 대화 상자 뒤에서 대기하는 동안에도 알림이 사용자에게 전달될 수 있습니다.
2459</Note>2465</Note>
2460 2466
2461Claude Code가 권한 요청을 Agent SDK의 [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)으로 보내는 세션에서는 `permission_prompt`의 타이밍이 다릅니다. Claude Desktop과 VS Code 확장 프로그램이 이 방식으로 Claude Code를 호스팅합니다.2467Claude Code가 권한 요청을 Agent SDK의 [`canUseTool` 콜백](/docs/ko/agent-sdk/user-input)으로 보내는 세션에서는 `permission_prompt`의 타이밍이 다릅니다. Claude Desktop과 VS Code 확장 프로그램이 이 방식으로 Claude Code를 호스팅합니다.
2462 2468
2463* `permission_prompt`는 Claude가 권한을 요청한 후 약 6초가 지나면 발생합니다. 사용자가 입력하는 동안에도 Claude Code는 이를 연기하지 않습니다.2469* `permission_prompt`는 Claude가 권한을 요청한 후 약 6초 뒤에 발생합니다. 사용자가 입력하는 동안에도 Claude Code는 이를 지연하지 않습니다.
2464* 사용자나 [PermissionRequest](#permissionrequest) 훅이 더 일찍 응답하면 Claude Code는 `permission_prompt`를 실행하지 않습니다.2470* 사용자 또는 [PermissionRequest](#permissionrequest) 훅이 그보다 먼저 응답하면 Claude Code는 `permission_prompt`를 실행하지 않습니다.
2465* 이러한 세션에서 `permission_prompt`를 끄려면 [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ko/env-vars)를 `1`로 설정합니다.2471* 이러한 세션에서 `permission_prompt`를 끄려면 [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/ko/env-vars)를 `1`로 설정합니다.
2466 2472
2467v2.1.233 이전에는 이러한 세션에서 `permission_prompt`가 발생하지 않았습니다.2473v2.1.233 이전에는 이러한 세션에서 `permission_prompt`가 발생하지 않았습니다.
2468 2474
2469알림 유형에 따라 서로 다른 핸들러를 실행하려면 별도의 matcher를 사용합니다. 다음 구성은 Claude가 권한 승인을 필요로 할 때 권한 전용 알림 스크립트를 트리거하고, Claude가 유휴 상태일 때 다른 알림을 트리거합니다.2475알림 유형에 따라 다른 핸들러를 실행하려면 별도의 matcher를 사용합니다. 이 구성은 Claude에 권한 승인이 필요할 때 권한 전용 알림 스크립트를 실행하고, Claude가 유휴 상태일 때 다른 알림을 실행합니다.
2470 2476
2471```json theme={null}2477```json theme={null}
2472{2478{
2496```2502```
2497 2503
2498<h4 id="notification-input">2504<h4 id="notification-input">
2499 Notification 입력2505 Notification input
2500</h4>2506</h4>
2501 2507
2502[공통 입력 필드](#common-input-fields) 외에도 Notification 훅은 알림 텍스트가 담긴 `message`, 선택적 `title`, 발생한 유형을 나타내는 `notification_type`을 전달받습니다.2508[공통 입력 필드](#common-input-fields) 외에도, Notification 훅은 알림 텍스트가 담긴 `message`, 선택적 `title`, 발생한 유형을 나타내는 `notification_type`을 전달받습니다.
2503 2509
2504```json theme={null}2510```json theme={null}
2505{2511{
2513}2519}
2514```2520```
2515 2521
2516Notification 훅은 알림을 차단하거나 수정할 수 없습니다. Claude Code는 이 훅의 `systemMessage` 및 `continue` 필드를 삭제하지만, 데스크톱 알림 예시가 사용하는 [`terminalSequence`](#emit-terminal-notifications)는 계속 내보냅니다. Notification 훅은 알림을 외부 서비스로 전달하는 것과 같은 부수 효과를 위한 것입니다.2522Notification 훅은 알림을 차단하거나 수정할 수 없습니다. Claude Code는 이 훅의 `systemMessage` 및 `continue` 필드를 삭제하지만, 데스크톱 알림 예시가 사용하는 [`terminalSequence`](#emit-terminal-notifications)는 여전히 내보냅니다. Notification 훅은 알림을 외부 서비스로 전달하는 것과 같은 부수 효과를 위한 것입니다.
2517 2523
2518<h3 id="subagentstart">2524<h3 id="subagentstart">
2519 SubagentStart2525 SubagentStart
2520</h3>2526</h3>
2521 2527
2522Claude가 Agent 도구로 서브에이전트를 생성할 때, Claude가 [서브에이전트를 재개](/docs/ko/sub-agents#resume-subagents)할 때, 그리고 프로세스 내 [에이전트 팀](/docs/ko/agent-teams) 팀원이 새 메시지를 처리할 때마다 실행됩니다. 에이전트 유형 이름으로 필터링하는 matcher를 지원합니다. 기본 제공 에이전트의 경우 `general-purpose`, `Explore`, `Plan`과 같은 에이전트 이름입니다. [사용자 정의 서브에이전트](/docs/ko/sub-agents)의 경우 파일 이름이 아니라 에이전트 frontmatter의 `name` 필드입니다.2528Claude가 Agent 도구로 서브에이전트를 생성할 때, Claude가 [서브에이전트를 재개](/docs/ko/sub-agents#resume-subagents)할 때, 그리고 프로세스 내 [에이전트 팀](/docs/ko/agent-teams) 팀원이 새 메시지를 처리할 때마다 실행됩니다. 에이전트 유형 이름으로 필터링하는 matcher를 지원합니다. 기본 제공 에이전트의 경우 `general-purpose`, `Explore`, `Plan` 같은 에이전트 이름입니다. [사용자 정의 서브에이전트](/docs/ko/sub-agents)의 경우 파일 이름이 아니라 에이전트 frontmatter의 `name` 필드입니다.
2523 2529
2524[플러그인](/docs/ko/plugins/overview)으로 제공되는 서브에이전트의 경우 에이전트 유형은 단순한 frontmatter 이름이 아니라 `my-plugin:reviewer`와 같은 플러그인 범위 식별자입니다. 콜론이 있으면 플러그인 범위 이름이 정규식 경로로 처리되므로, 정확히 매칭하려면 matcher를 `^`와 `$`로 고정합니다: `^my-plugin:reviewer$`.2530[플러그인](/docs/ko/plugins/overview)이 제공하는 서브에이전트의 경우, 에이전트 유형은 frontmatter의 이름만이 아니라 `my-plugin:reviewer`와 같은 플러그인 범위 식별자입니다. 콜론 때문에 플러그인 범위 이름은 정규식 경로로 처리되므로, 정확히 매칭하려면 matcher를 `^`와 `$`로 고정합니다. 예: `^my-plugin:reviewer$`.
2525 2531
2526<h4 id="subagentstart-input">2532<h4 id="subagentstart-input">
2527 SubagentStart 입력2533 SubagentStart input
2528</h4>2534</h4>
2529 2535
2530[공통 입력 필드](#common-input-fields) 외에도 SubagentStart 훅은 서브에이전트의 고유 식별자가 담긴 `agent_id`와 matcher가 필터링하는 에이전트 이름이 담긴 `agent_type`을 전달받습니다.2536[공통 입력 필드](#common-input-fields) 외에도, SubagentStart 훅은 서브에이전트의 고유 식별자가 담긴 `agent_id`와 matcher가 필터링하는 에이전트 이름이 담긴 `agent_type`을 전달받습니다.
2531 2537
2532```json theme={null}2538```json theme={null}
2533{2539{
2544 2550
2545| 필드 | 설명 |2551| 필드 | 설명 |
2546| :- | :- |2552| :- | :- |
2547| `additionalContext` | 서브에이전트의 대화 시작 시, 첫 프롬프트 전에 서브에이전트의 컨텍스트에 추가되는 문자열입니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |2553| `additionalContext` | 서브에이전트의 대화 시작 시, 첫 프롬프트 전에 서브에이전트의 컨텍스트에 추가되는 문자열입니다. [Claude에 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |
2548 2554
2549```json theme={null}2555```json theme={null}
2550{2556{
2555}2561}
2556```2562```
2557 2563
2558같은 서브에이전트에 대해 훅이 다시 실행되면, Claude Code는 서브에이전트의 컨텍스트에 이전 실행의 사본이 아직 없는 경우에만 반환된 컨텍스트를 주입합니다. 시작 시 주입된 사본은 그대로 유지되므로 서브에이전트의 [프롬프트 캐시](/docs/ko/prompt-caching#subagents-and-the-cache)가 손상되지 않습니다. [자동 압축](/docs/ko/sub-agents#auto-compaction)으로 해당 사본이 삭제된 후에는 Claude Code가 다음 실행의 컨텍스트를 다시 주입합니다.2564같은 서브에이전트에 대해 훅이 다시 실행되면, Claude Code는 서브에이전트의 컨텍스트에 이전 실행의 사본이 아직 없는 경우에만 반환된 컨텍스트를 주입합니다. 시작 시 주입된 사본은 그대로 유지되므로 서브에이전트의 [프롬프트 캐시](/docs/ko/prompt-caching#subagents-and-the-cache)가 손상되지 않습니다. [자동 압축](/docs/ko/sub-agents#auto-compaction)이 해당 사본을 삭제한 후에는 Claude Code가 다음 실행의 컨텍스트를 다시 주입합니다.
2559 2565
2560<h3 id="subagentstop">2566<h3 id="subagentstop">
2561 SubagentStop2567 SubagentStop
2562</h3>2568</h3>
2563 2569
2564Claude Code 서브에이전트가 응답을 마쳤을 때 실행됩니다. 에이전트 유형으로 매칭하며, 값은 SubagentStart와 같습니다.2570Claude Code 서브에이전트가 응답을 마쳤을 때 실행됩니다. 에이전트 유형으로 매칭하며, SubagentStart와 같은 값을 사용합니다.
2565 2571
2566<h4 id="subagentstop-input">2572<h4 id="subagentstop-input">
2567 SubagentStop 입력2573 SubagentStop input
2568</h4>2574</h4>
2569 2575
2570[공통 입력 필드](#common-input-fields) 외에도 SubagentStop 훅은 `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, `last_assistant_message`를 전달받습니다. `agent_type` 필드는 matcher 필터링에 사용되는 값입니다. `transcript_path`는 메인 세션의 트랜스크립트이고, `agent_transcript_path`는 중첩된 `subagents/` 폴더에 저장된 서브에이전트 자체의 트랜스크립트입니다. `last_assistant_message` 필드에는 서브에이전트의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다.2576[공통 입력 필드](#common-input-fields) 외에도, SubagentStop 훅은 `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, `last_assistant_message`를 전달받습니다. `agent_type` 필드는 matcher 필터링에 사용되는 값입니다. `transcript_path`는 메인 세션의 트랜스크립트이고, `agent_transcript_path`는 중첩된 `subagents/` 폴더에 저장된 서브에이전트 자체의 트랜스크립트입니다. `last_assistant_message` 필드에는 서브에이전트의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다.
2571 2577
2572모든 SubagentStop 이벤트가 Claude가 생성한 서브에이전트에서 오는 것은 아닙니다. Claude Code는 [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions) 및 [`/btw` 곁가지 질문](/docs/ko/interactive-mode#side-questions-with-%2Fbtw)과 같은 일부 자체 기능을 위해 내부 에이전트도 실행하며, 이러한 에이전트 중 하나가 완료될 때도 SubagentStop이 발생합니다. 이러한 이벤트의 경우 `agent_type`은 [`--agent`](/docs/ko/cli-reference#cli-flags) 또는 [`agent` 설정](/docs/ko/settings-reference#agent)으로 지정된 것처럼 세션 자체가 실행되는 에이전트 이름이며, 세션이 에이전트 없이 실행되는 경우 빈 문자열입니다.2578모든 SubagentStop 이벤트가 Claude가 생성한 서브에이전트에서 오는 것은 아닙니다. Claude Code는 [프롬프트 제안](/docs/ko/interactive-mode#prompt-suggestions)이나 [`/btw` 부가 질문](/docs/ko/interactive-mode#side-questions-with-%2Fbtw) 같은 일부 자체 기능을 위해 내부 에이전트도 실행하며, 이들 중 하나가 완료될 때도 SubagentStop이 발생합니다. 이러한 이벤트의 경우 `agent_type`은 [`--agent`](/docs/ko/cli-reference#cli-flags) 또는 [`agent` 설정](/docs/ko/settings-reference#agent)으로 지정된 것처럼 세션 자체가 실행되는 에이전트 이름이며, 세션이 에이전트 없이 실행되면 빈 문자열입니다.
2573 2579
2574에이전트 유형을 지정하는 `matcher`는 빈 `agent_type`과 매칭되지 않습니다. matcher가 생략되었거나, `""` 또는 `"*"`이거나, 빈 문자열과 매칭되는 정규식인 훅은 빈 `agent_type`을 가진 이벤트에서도 실행됩니다.2580에이전트 유형을 지정한 `matcher`는 빈 `agent_type`과 매칭되지 않습니다. matcher가 생략되었거나, `""` 또는 `"*"`이거나, 빈 문자열과 매칭되는 정규식인 훅은 빈 `agent_type`을 가진 이벤트에도 실행됩니다.
2575 2581
2576Claude Code v2.1.271 이상에서는 [`SubagentHandback`](/docs/ko/tools-reference) 도구와 함께 실행되는 서브에이전트가 중지되기 전에 해당 도구를 통해 보고서를 전달합니다. 이 경우 `last_assistant_message` 필드에는 서브에이전트의 마무리 텍스트(있는 경우)가 담기며, 이는 전달된 보고서가 아닙니다. 보고서는 해당 호출의 `message` 입력이며, `SubagentHandback`에 매칭되는 `PreToolUse` 또는 `PostToolUse` 훅이 이를 `tool_input.message`로 전달받습니다.2582Claude Code v2.1.271 이상에서는 [`SubagentHandback`](/docs/ko/tools-reference) 도구와 함께 실행되는 서브에이전트가 중지되기 전에 해당 도구를 통해 보고서를 전달합니다. 이때 `last_assistant_message` 필드에는 서브에이전트의 마무리 텍스트가 있으면 그것이 담기며, 이는 전달된 보고서가 아닙니다. 보고서는 해당 호출의 `message` 입력이며, `SubagentHandback`에 매칭되는 `PreToolUse` 또는 `PostToolUse` 훅은 이를 `tool_input.message`로 전달받습니다.
2577 2583
2578SubagentStop 훅은 [Stop 입력](#stop-input)에서 설명하는 `background_tasks` 및 `session_crons` 배열도 전달받습니다. 두 배열 모두 서브에이전트가 아닌 부모 세션 범위입니다.2584SubagentStop 훅은 [Stop 입력](#stop-input)에서 설명하는 `background_tasks` 및 `session_crons` 배열도 전달받습니다. 두 배열 모두 서브에이전트가 아닌 상위 세션 범위입니다.
2579 2585
2580```json theme={null}2586```json theme={null}
2581{2587{
2594}2600}
2595```2601```
2596 2602
2597SubagentStop 훅은 [Stop 훅](#stop-decision-control)과 같은 결정 제어 형식을 사용하며, 여기에는 서브에이전트를 계속 실행시키는 오류가 아닌 피드백을 위해 `hookEventName`을 `"SubagentStop"`으로 설정한 `hookSpecificOutput.additionalContext`도 포함됩니다. `reason`과 함께 `decision: "block"`을 반환하면 서브에이전트가 계속 실행되며 `reason`이 서브에이전트의 다음 지시로 전달됩니다. 종료 코드 2로 차단하는 훅도 같은 방식으로 stderr 메시지를 전달합니다. 서브에이전트가 반환된 후 부모 세션에 컨텍스트를 주입하려면 대신 `Agent` 도구에 대한 [`PostToolUse`](#posttooluse) 훅을 사용합니다.2603SubagentStop 훅은 [Stop 훅](#stop-decision-control)과 같은 결정 제어 형식을 사용하며, 서브에이전트를 계속 실행시키는 오류가 아닌 피드백을 위해 `hookEventName`을 `"SubagentStop"`으로 설정한 `hookSpecificOutput.additionalContext`도 포함됩니다. `reason`과 함께 `decision: "block"`을 반환하면 서브에이전트가 계속 실행되며 `reason`이 서브에이전트의 다음 지시로 전달됩니다. 종료 코드 2로 차단하는 훅은 stderr 메시지를 같은 방식으로 전달합니다. 서브에이전트가 반환된 후 상위 세션에 컨텍스트를 주입하려면 대신 `Agent` 도구에 대한 [`PostToolUse`](#posttooluse) 훅을 사용합니다.
2598 2604
2599<h3 id="taskcreated">2605<h3 id="taskcreated">
2600 TaskCreated2606 TaskCreated
2601</h3>2607</h3>
2602 2608
2603`TaskCreate` 도구를 통해 작업이 생성될 때 실행됩니다. 명명 규칙을 적용하거나, 작업 설명을 필수로 요구하거나, 특정 작업이 생성되지 않도록 막는 데 사용합니다. [Task 도구가 없는 세션](/docs/ko/tools-reference#task-tool-availability)에서는 이 이벤트가 발생하지 않습니다.2609`TaskCreate` 도구를 통해 작업이 생성될 때 실행됩니다. 명명 규칙을 적용하거나, 작업 설명을 필수로 요구하거나, 특정 작업의 생성을 방지하는 데 사용합니다. [Task 도구가 없는 세션](/docs/ko/tools-reference#task-tool-availability)에서는 이 이벤트가 발생하지 않습니다.
2604 2610
2605TaskCreated 훅은 matcher를 지원하지 않으며 매번 발생합니다.2611TaskCreated 훅은 matcher를 지원하지 않으며 매번 발생합니다.
2606 2612
2607<h4 id="taskcreated-input">2613<h4 id="taskcreated-input">
2608 TaskCreated 입력2614 TaskCreated input
2609</h4>2615</h4>
2610 2616
2611[공통 입력 필드](#common-input-fields) 외에도 TaskCreated 훅은 `task_id`, `task_subject`와 선택적으로 `task_description`, `teammate_name`, `team_name`을 전달받습니다.2617[공통 입력 필드](#common-input-fields) 외에도, TaskCreated 훅은 `task_id`, `task_subject`를 전달받으며, 선택적으로 `task_description`, `teammate_name`, `team_name`을 전달받습니다.
2612 2618
2613```json theme={null}2619```json theme={null}
2614{2620{
2626 2632
2627| 필드 | 설명 |2633| 필드 | 설명 |
2628| :- | :- |2634| :- | :- |
2629| `task_id` | 생성 중인 작업의 식별자입니다 |2635| `task_id` | 생성되는 작업의 식별자입니다 |
2630| `task_subject` | 작업의 제목입니다 |2636| `task_subject` | 작업의 제목입니다 |
2631| `task_description` | 작업의 상세 설명입니다. 없을 수도 있습니다 |2637| `task_description` | 작업에 대한 자세한 설명입니다. 없을 수도 있습니다 |
2632| `teammate_name` | 작업을 생성하는 팀원의 이름입니다. 없을 수도 있습니다 |2638| `teammate_name` | 작업을 생성하는 팀원의 이름입니다. 없을 수도 있습니다 |
2633| `team_name` | Deprecated. 세션에서 파생된 팀 이름이며, 향후 릴리스에서 제거될 예정입니다 |2639| `team_name` | Deprecated. 세션에서 파생된 팀 이름이며, 향후 릴리스에서 제거됩니다 |
2634 2640
2635<h4 id="taskcreated-decision-control">2641<h4 id="taskcreated-decision-control">
2636 TaskCreated 결정 제어2642 TaskCreated decision control
2637</h4>2643</h4>
2638 2644
2639TaskCreated 훅은 두 가지 방법으로 생성을 차단할 수 있습니다. 어느 방법이든 Claude Code는 작업을 삭제하고 메시지를 도구의 오류로 Claude에게 반환합니다. Claude Code는 이 이벤트의 `continue: false`를 무시하며 Claude는 계속 작업합니다.2645TaskCreated 훅은 두 가지 방법으로 생성을 차단할 수 있습니다. 어느 방법이든 Claude Code는 작업을 삭제하고 메시지를 도구의 오류로 Claude에 반환합니다. Claude Code는 이 이벤트의 `continue: false`를 무시하며 Claude는 계속 작업합니다.
2640 2646
2641* **종료 코드 2**: Claude Code가 stderr 텍스트를 메시지로 반환합니다.2647* **종료 코드 2**: Claude Code가 stderr 텍스트를 메시지로 반환합니다.
2642* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code가 `reason`을 메시지로 반환합니다.2648* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code가 `reason`을 메시지로 반환합니다.
2660 TaskCompleted2666 TaskCompleted
2661</h3>2667</h3>
2662 2668
2663작업이 완료로 표시될 때 실행됩니다. 이 이벤트는 두 가지 상황에서 발생합니다. 어떤 에이전트든 TaskUpdate 도구를 통해 작업을 명시적으로 완료로 표시하는 경우, 또는 [에이전트 팀](/docs/ko/agent-teams) 팀원이 진행 중인 작업이 있는 상태에서 턴을 마치는 경우입니다. 작업이 종료되기 전에 테스트 통과나 린트 검사와 같은 완료 기준을 적용하는 데 사용합니다.2669작업이 완료로 표시될 때 실행됩니다. 두 가지 상황에서 발생합니다. 에이전트가 TaskUpdate 도구를 통해 작업을 명시적으로 완료로 표시할 때, 또는 [에이전트 팀](/docs/ko/agent-teams) 팀원이 진행 중인 작업이 있는 상태로 턴을 마칠 때입니다. 작업을 종료하기 전에 테스트 통과나 lint 검사 같은 완료 기준을 적용하는 데 사용합니다.
2664 2670
2665TaskCompleted 훅은 matcher를 지원하지 않으며 매번 발생합니다.2671TaskCompleted 훅은 matcher를 지원하지 않으며 매번 발생합니다.
2666 2672
2667<h4 id="taskcompleted-input">2673<h4 id="taskcompleted-input">
2668 TaskCompleted 입력2674 TaskCompleted input
2669</h4>2675</h4>
2670 2676
2671[공통 입력 필드](#common-input-fields) 외에도 TaskCompleted 훅은 `task_id`, `task_subject`와 선택적으로 `task_description`, `teammate_name`, `team_name`을 전달받습니다.2677[공통 입력 필드](#common-input-fields) 외에도, TaskCompleted 훅은 `task_id`, `task_subject`를 전달받으며, 선택적으로 `task_description`, `teammate_name`, `team_name`을 전달받습니다.
2672 2678
2673```json theme={null}2679```json theme={null}
2674{2680{
2687 2693
2688| 필드 | 설명 |2694| 필드 | 설명 |
2689| :- | :- |2695| :- | :- |
2690| `task_id` | 완료 중인 작업의 식별자입니다 |2696| `task_id` | 완료되는 작업의 식별자입니다 |
2691| `task_subject` | 작업의 제목입니다 |2697| `task_subject` | 작업의 제목입니다 |
2692| `task_description` | 작업의 상세 설명입니다. 없을 수도 있습니다 |2698| `task_description` | 작업에 대한 자세한 설명입니다. 없을 수도 있습니다 |
2693| `teammate_name` | 작업을 완료하는 팀원의 이름입니다. 없을 수도 있습니다 |2699| `teammate_name` | 작업을 완료하는 팀원의 이름입니다. 없을 수도 있습니다 |
2694| `team_name` | Deprecated. 세션에서 파생된 팀 이름이며, 향후 릴리스에서 제거될 예정입니다 |2700| `team_name` | Deprecated. 세션에서 파생된 팀 이름이며, 향후 릴리스에서 제거됩니다 |
2695 2701
2696<h4 id="taskcompleted-decision-control">2702<h4 id="taskcompleted-decision-control">
2697 TaskCompleted 결정 제어2703 TaskCompleted decision control
2698</h4>2704</h4>
2699 2705
2700TaskCompleted 훅은 작업 완료를 제어하는 두 가지 방법을 지원합니다.2706TaskCompleted 훅은 작업 완료를 제어하는 두 가지 방법을 지원합니다.
2701 2707
2702* **종료 코드 2**: 작업이 완료로 표시되지 않으며 stderr 메시지가 피드백으로 모델에 전달됩니다.2708* **종료 코드 2**: 작업이 완료로 표시되지 않으며 stderr 메시지가 피드백으로 모델에 전달됩니다.
2703* **JSON `{"continue": false, "stopReason": "..."}`**: 팀원이 턴을 마치면서 이벤트가 트리거된 경우, `Stop` 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. `stopReason`은 사용자에게 표시됩니다. `TaskUpdate` 도구가 이벤트를 트리거한 경우 Claude Code는 `continue: false`를 무시하며, 종료 코드 2는 여전히 완료를 차단합니다.2709* **JSON `{"continue": false, "stopReason": "..."}`**: 팀원이 턴을 마쳐서 이벤트가 발생한 경우, `Stop` 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. `stopReason`은 사용자에게 표시됩니다. `TaskUpdate` 도구가 이벤트를 발생시킨 경우에는 Claude Code가 `continue: false`를 무시하며, 종료 코드 2는 여전히 완료를 차단합니다.
2704 2710
2705이 예시는 테스트를 실행하고 테스트가 실패하면 작업 완료를 차단합니다.2711이 예시는 테스트를 실행하고 실패하면 작업 완료를 차단합니다.
2706 2712
2707```bash theme={null}2713```bash theme={null}
2708#!/bin/bash2714#!/bin/bash
2722 Stop2728 Stop
2723</h3>2729</h3>
2724 2730
2725메인 Claude Code 에이전트가 응답을 마쳤을 때 실행됩니다. 사용자 중단으로 인해2731메인 Claude Code 에이전트가 응답을 마쳤을 때 실행됩니다. 사용자 중단으로
2726중지된 경우에는 실행되지 않습니다. API 오류는 대신2732중지된 경우에는 실행되지 않습니다. API 오류가 발생하면 대신
2727[StopFailure](#stopfailure)를 발생시킵니다.2733[StopFailure](#stopfailure)가 발생합니다.
2728 2734
2729<Tip>2735<Tip>
2730 [`/goal`](/docs/ko/goal) 명령은 세션 범위의 프롬프트 기반 Stop 훅을 위한 기본 제공 단축 기능입니다. 훅 구성을 작성하지 않고도 Claude가 특정 조건을 향해 계속 작업하도록 하려는 경우에 사용합니다.2736 [`/goal`](/docs/ko/goal) 명령은 세션 범위의 프롬프트 기반 Stop 훅을 위한 기본 제공 단축 명령입니다. 훅 구성을 작성하지 않고 Claude가 특정 조건을 향해 계속 작업하게 하려면 이 명령을 사용합니다.
2731</Tip>2737</Tip>
2732 2738
2733<h4 id="stop-input">2739<h4 id="stop-input">
2734 Stop 입력2740 Stop input
2735</h4>2741</h4>
2736 2742
2737[공통 입력 필드](#common-input-fields) 외에도 Stop 훅은 `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons`를 전달받습니다. `stop_hook_active` 필드는 Claude Code가 이미 stop 훅의 결과로 계속 진행 중인 경우 `true`입니다. 결코 해결되지 않을 조건에서 차단하지 않도록 이 값을 확인하거나 트랜스크립트를 처리합니다. Claude Code는 연속 계속 진행 횟수를 8회로 제한합니다. stop 훅이 턴을 연속으로 8번 계속 진행시킨 후에는 Claude Code가 다음 차단을 재정의하고 턴을 종료합니다. 이 제한을 높이려면 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ko/env-vars)을 설정합니다.2743[공통 입력 필드](#common-input-fields) 외에도, Stop 훅은 `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons`를 전달받습니다. `stop_hook_active` 필드는 Claude Code가 이미 stop 훅의 결과로 계속 진행 중일 때 `true`입니다. 절대 해결되지 않을 조건으로 차단하지 않도록 이 값을 확인하거나 트랜스크립트를 처리합니다. Claude Code는 연속 8회 계속 진행 한도를 적용합니다. stop 훅이 턴을 연속으로 8번 계속 진행시킨 후에는 Claude Code가 다음 차단을 재정의하고 턴을 종료합니다. 한도를 높이려면 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ko/env-vars)을 설정합니다.
2738 2744
2739`last_assistant_message` 필드에는 Claude의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다. 소리 내어 읽기 훅이나 알림 훅처럼 방금 완료된 턴에 대해 작동하는 훅의 경우 `transcript_path`를 읽는 대신 이 필드를 사용합니다. 모든 버전에서 Stop 시점에 트랜스크립트 파일에 최종 메시지가 포함된다고 보장되지 않기 때문입니다.2745`last_assistant_message` 필드에는 Claude의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다. 소리 내어 읽기나 알림 훅처럼 방금 완료된 턴에 대해 동작하는 훅은 `transcript_path`를 읽는 대신 이 필드를 사용합니다. 모든 버전에서 Stop 시점에 트랜스크립트 파일에 최종 메시지가 포함된다는 보장이 없기 때문입니다.
2740 2746
2741`background_tasks` 및 `session_crons` 배열을 사용하면 훅이 "세션이 완료됨"과 "백그라운드 작업이 세션을 다시 깨울 때까지 일시 중지됨"을 구별할 수 있습니다. 두 배열은 작업 레지스트리에 접근할 수 있을 때 존재하며, 진행 중이거나 예약된 것이 없으면 비어 있습니다.2747`background_tasks` 및 `session_crons` 배열을 사용하면 훅이 "세션이 완료됨"과 "세션이 백그라운드 작업이 다시 깨워 주기를 기다리며 일시 중지됨"을 구분할 수 있습니다. 두 배열은 작업 레지스트리에 접근할 수 있을 때 존재하며, 진행 중이거나 예약된 것이 없으면 비어 있습니다.
2742 2748
2743`background_tasks`의 각 항목은 진행 중인 작업 하나를 설명하며 다음 필드를 사용합니다.2749`background_tasks`의 각 항목은 진행 중인 작업 하나를 설명하며 다음 필드를 사용합니다.
2744 2750
2745| 필드 | 설명 |2751| 필드 | 설명 |
2746| :- | :- |2752| :- | :- |
2747| `id` | 작업 식별자입니다 |2753| `id` | 작업 식별자입니다 |
2748| `type` | `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, `MCP task`와 같은 읽기 쉬운 작업 유형 레이블입니다. 각 레이블은 어떤 Claude Code 기능이 작업을 생성했는지 식별합니다. 인식되지 않는 유형의 경우 원시 판별값으로 대체됩니다 |2754| `type` | `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, `MCP task`와 같은 알기 쉬운 작업 유형 레이블입니다. 각 레이블은 작업을 생성한 Claude Code 기능을 나타냅니다. 인식되지 않는 유형의 경우 원시 판별값으로 대체됩니다 |
2749| `status` | 현재 작업 상태입니다 |2755| `status` | 현재 작업 상태입니다 |
2750| `description` | 자유 형식 설명이며, 1000자로 제한되고 잘린 경우 문자열 안에 `… [+N chars]` 마커가 표시됩니다 |2756| `description` | 자유 형식 설명으로, 1000자로 제한되며 잘린 경우 문자열 내에 `… [+N chars]` 마커가 붙습니다 |
2751| `command` | 셸 명령줄이며, 1000자로 제한됩니다. `shell` 작업에만 존재합니다 |2757| `command` | 셸 명령줄로, 1000자로 제한됩니다. `shell` 작업에만 있습니다 |
2752| `agent_type` | 서브에이전트 유형 이름입니다. `subagent` 작업에만 존재합니다 |2758| `agent_type` | 서브에이전트 유형 이름입니다. `subagent` 작업에만 있습니다 |
2753| `server` | MCP 서버 이름입니다. `monitor` 및 `MCP task` 작업에만 존재합니다 |2759| `server` | MCP 서버 이름입니다. `monitor` 및 `MCP task` 작업에만 있습니다 |
2754| `tool` | MCP 도구 이름입니다. `monitor` 및 `MCP task` 작업에만 존재합니다 |2760| `tool` | MCP 도구 이름입니다. `monitor` 및 `MCP task` 작업에만 있습니다 |
2755| `name` | 워크플로 이름입니다. `workflow` 작업에만 존재합니다 |2761| `name` | 워크플로 이름입니다. `workflow` 작업에만 있습니다 |
2756 2762
2757`session_crons`의 각 항목은 `CronCreate`, `ScheduleWakeup`, `/loop`에서 가져온 세션 범위의 예약된 깨우기 하나를 설명합니다.2763`session_crons`의 각 항목은 `CronCreate`, `ScheduleWakeup`, `/loop`에서 생성된 세션 범위의 예약된 깨우기 하나를 설명합니다.
2758 2764
2759| 필드 | 설명 |2765| 필드 | 설명 |
2760| :- | :- |2766| :- | :- |
2761| `id` | Cron 작업 식별자입니다 |2767| `id` | Cron 작업 식별자입니다 |
2762| `schedule` | Cron 표현식입니다(예: `0 9 * * 1-5`) |2768| `schedule` | Cron 표현식입니다. 예: `0 9 * * 1-5` |
2763| `recurring` | 일정이 단일 실행 시점을 나타내는 일회성 깨우기는 `false`, 매칭될 때마다 다시 실행되는 작업은 `true`입니다 |2769| `recurring` | 일정이 단일 실행 시각을 나타내는 일회성 깨우기는 `false`, 매칭될 때마다 다시 실행되는 작업은 `true`입니다 |
2764| `prompt` | cron이 실행될 때 제출되는 프롬프트이며, 1000자로 제한되고 동일한 `… [+N chars]` 마커가 사용됩니다 |2770| `prompt` | cron이 실행될 때 제출되는 프롬프트로, 1000자로 제한되며 같은 `… [+N chars]` 마커가 붙습니다 |
2765 2771
2766이 예시는 진행 중인 셸 작업 하나와 반복 cron 하나가 있는 Stop 입력을 보여 줍니다.2772이 예시는 진행 중인 셸 작업 하나와 반복 cron 하나가 있는 Stop 입력을 보여 줍니다.
2767 2773
2795```2801```
2796 2802
2797<h4 id="stop-decision-control">2803<h4 id="stop-decision-control">
2798 Stop 결정 제어2804 Stop decision control
2799</h4>2805</h4>
2800 2806
2801`Stop` 및 `SubagentStop` 훅은 Claude의 계속 진행 여부를 제어할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.2807`Stop` 및 `SubagentStop` 훅은 Claude의 계속 진행 여부를 제어할 수 있습니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도, 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.
2802 2808
2803| 필드 | 설명 |2809| 필드 | 설명 |
2804| :- | :- |2810| :- | :- |
2805| `decision` | `"block"`은 Claude가 중지되지 않도록 합니다. Claude가 중지되도록 허용하려면 생략합니다 |2811| `decision` | `"block"`은 Claude가 중지하지 못하게 합니다. Claude가 중지하도록 허용하려면 생략합니다 |
2806| `reason` | `decision`이 `"block"`일 때 필수입니다. Claude에게 계속 진행해야 하는 이유를 알려 줍니다 |2812| `reason` | `decision`이 `"block"`일 때 필수입니다. Claude에 계속해야 하는 이유를 알려 줍니다 |
2807| `hookSpecificOutput.additionalContext` | Claude를 위한 오류가 아닌 피드백입니다. Claude가 이에 따라 조치할 수 있도록 대화가 계속되지만, `decision: "block"`과 달리 트랜스크립트에 훅 오류가 아닌 훅 피드백으로 표시됩니다 |2813| `hookSpecificOutput.additionalContext` | Claude를 위한 오류가 아닌 피드백입니다. Claude가 이에 따라 조치할 수 있도록 대화가 계속되지만, `decision: "block"`과 달리 트랜스크립트에 훅 오류가 아닌 훅 피드백으로 표시됩니다 |
2808 2814
2809종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. Claude는 stderr 메시지를 계속 진행해야 하는 이유에 대한 설명으로 전달받습니다.2815종료 코드 2로 차단하는 훅은 `reason`과 같은 방식으로 전달됩니다. Claude는 stderr 메시지를 계속해야 하는 이유에 대한 설명으로 받습니다.
2810 2816
2811```json theme={null}2817```json theme={null}
2812{2818{
2815}2821}
2816```2822```
2817 2823
2818훅이 설계대로 작동하면서 "완료하기 전에 테스트 스위트 실행"과 같은 지침을 Claude에게 제공하는 경우 `additionalContext`를 사용합니다. 이 필드는 `decision: "block"`과 같은 루프 보호 장치, 즉 `stop_hook_active` 입력과 연속 계속 진행 8회 제한을 거쳐 대화를 계속 진행하지만, 트랜스크립트에는 `Stop hook feedback`으로 표시되고 훅 오류 알림은 표시되지 않습니다.2824훅이 설계대로 작동하면서 "완료하기 전에 테스트 스위트 실행"과 같은 안내를 Claude에 제공할 때는 `additionalContext`를 사용합니다. 이 방법은 `decision: "block"`과 같은 루프 보호 장치, 즉 `stop_hook_active` 입력과 연속 8회 계속 진행 한도를 거쳐 대화를 계속하지만, 트랜스크립트에는 `Stop hook feedback`으로 레이블이 지정되며 훅 오류 알림은 표시되지 않습니다.
2819 2825
2820```json theme={null}2826```json theme={null}
2821{2827{
2830 StopFailure2836 StopFailure
2831</h3>2837</h3>
2832 2838
2833API 오류로 인해 턴이 종료될 때 [Stop](#stop) 대신 실행됩니다. Claude Code는 [`terminalSequence`](#emit-terminal-notifications)를 제외한 훅의 출력과 종료 코드를 무시합니다. 속도 제한, 인증 문제 또는 기타 API 오류로 인해 Claude가 응답을 완료할 수 없을 때 실패를 로그에 기록하거나, 알림을 보내거나, 복구 조치를 취하는 데 사용합니다.2839API 오류로 턴이 끝날 때 [Stop](#stop) 대신 실행됩니다. Claude Code는 [`terminalSequence`](#emit-terminal-notifications)를 제외하고 훅의 출력과 종료 코드를 무시합니다. 속도 제한, 인증 문제 또는 기타 API 오류로 Claude가 응답을 완료할 수 없을 때 실패를 로그에 기록하거나, 알림을 보내거나, 복구 조치를 취하는 데 사용합니다.
2834 2840
2835<h4 id="stopfailure-input">2841<h4 id="stopfailure-input">
2836 StopFailure 입력2842 StopFailure input
2837</h4>2843</h4>
2838 2844
2839[공통 입력 필드](#common-input-fields) 외에도 StopFailure 훅은 `error`, 선택적 `error_details`, 선택적 `last_assistant_message`를 전달받습니다. `error` 필드는 오류 유형을 식별하며 matcher 필터링에 사용됩니다.2845[공통 입력 필드](#common-input-fields) 외에도, StopFailure 훅은 `error`, 선택적 `error_details`, 선택적 `last_assistant_message`를 전달받습니다. `error` 필드는 오류 유형을 식별하며 matcher 필터링에 사용됩니다.
2840 2846
2841| 필드 | 설명 |2847| 필드 | 설명 |
2842| :- | :- |2848| :- | :- |
2843| `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` |2849| `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` |
2844| `error_details` | 사용 가능한 경우 오류에 대한 추가 세부 정보입니다 |2850| `error_details` | 사용 가능한 경우 오류에 대한 추가 세부 정보입니다 |
2845| `last_assistant_message` | 대화에 표시된 렌더링된 오류 텍스트입니다. 이 필드에 Claude의 대화 출력이 담기는 `Stop` 및 `SubagentStop`과 달리, `StopFailure`에서는 `"API Error: Rate limit reached"`와 같은 API 오류 문자열 자체가 담깁니다 |2851| `last_assistant_message` | 대화에 표시되는 렌더링된 오류 텍스트입니다. 이 필드에 Claude의 대화 출력이 담기는 `Stop` 및 `SubagentStop`과 달리, `StopFailure`에서는 `"API Error: Rate limit reached"`와 같은 API 오류 문자열 자체가 담깁니다 |
2846 2852
2847```json theme={null}2853```json theme={null}
2848{2854{
2862 TeammateIdle2868 TeammateIdle
2863</h3>2869</h3>
2864 2870
2865[에이전트 팀](/docs/ko/agent-teams) 팀원이 턴을 마친 후 유휴 상태가 되려고 할 때 실행됩니다. 린트 검사 통과를 요구하거나 출력 파일이 존재하는지 확인하는 등, 팀원이 작업을 멈추기 전에 품질 기준을 적용하는 데 사용합니다.2871[에이전트 팀](/docs/ko/agent-teams) 팀원이 턴을 마친 후 유휴 상태로 전환되려고 할 때 실행됩니다. lint 검사 통과를 요구하거나 출력 파일이 존재하는지 확인하는 것처럼, 팀원이 작업을 멈추기 전에 품질 기준을 적용하는 데 사용합니다.
2866 2872
2867TeammateIdle 훅은 matcher를 지원하지 않으며 매번 발생합니다.2873TeammateIdle 훅은 matcher를 지원하지 않으며 매번 발생합니다.
2868 2874
2869<h4 id="teammateidle-input">2875<h4 id="teammateidle-input">
2870 TeammateIdle 입력2876 TeammateIdle input
2871</h4>2877</h4>
2872 2878
2873[공통 입력 필드](#common-input-fields) 외에도 TeammateIdle 훅은 `teammate_name`과 `team_name`을 전달받습니다.2879[공통 입력 필드](#common-input-fields) 외에도, TeammateIdle 훅은 `teammate_name`과 `team_name`을 전달받습니다.
2874 2880
2875```json theme={null}2881```json theme={null}
2876{2882{
2886 2892
2887| 필드 | 설명 |2893| 필드 | 설명 |
2888| :- | :- |2894| :- | :- |
2889| `teammate_name` | 유휴 상태가 되려는 팀원의 이름입니다 |2895| `teammate_name` | 유휴 상태로 전환되려는 팀원의 이름입니다 |
2890| `team_name` | Deprecated. 세션에서 파생된 팀 이름이며, 향후 릴리스에서 제거될 예정입니다 |2896| `team_name` | Deprecated. 세션에서 파생된 팀 이름이며, 향후 릴리스에서 제거됩니다 |
2891 2897
2892<h4 id="teammateidle-decision-control">2898<h4 id="teammateidle-decision-control">
2893 TeammateIdle 결정 제어2899 TeammateIdle decision control
2894</h4>2900</h4>
2895 2901
2896TeammateIdle 훅은 팀원 동작을 제어하는 두 가지 방법을 지원합니다.2902TeammateIdle 훅은 팀원 동작을 제어하는 두 가지 방법을 지원합니다.
2897 2903
2898* **종료 코드 2**: 팀원이 stderr 메시지를 피드백으로 받고 유휴 상태가 되는 대신 계속 작업합니다.2904* **종료 코드 2**: 팀원이 stderr 메시지를 피드백으로 받고 유휴 상태로 전환되는 대신 계속 작업합니다.
2899* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. `stopReason`은 사용자에게 표시됩니다.2905* **JSON `{"continue": false, "stopReason": "..."}`**: `Stop` 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. `stopReason`은 사용자에게 표시됩니다.
2900 2906
2901이 예시는 팀원이 유휴 상태가 되도록 허용하기 전에 빌드 산출물이 존재하는지 확인합니다.2907이 예시는 팀원이 유휴 상태로 전환되도록 허용하기 전에 빌드 산출물이 존재하는지 확인합니다.
2902 2908
2903```bash theme={null}2909```bash theme={null}
2904#!/bin/bash2910#!/bin/bash
2917 2923
2918세션 중에 설정 파일이 변경될 때 실행됩니다. 설정 변경을 감사하거나, 보안 정책을 적용하거나, 설정 파일에 대한 무단 수정을 차단하는 데 사용합니다.2924세션 중에 설정 파일이 변경될 때 실행됩니다. 설정 변경을 감사하거나, 보안 정책을 적용하거나, 설정 파일에 대한 무단 수정을 차단하는 데 사용합니다.
2919 2925
2920Claude Code는 설정 파일, 관리형 정책 파일 또는 스킬 파일이 변경될 때 ConfigChange 훅을 실행합니다. 관리형 정책의 경우 `managed-settings.json` 또는 `managed-settings.d/`의 파일이 변경될 때만 실행합니다. [서버 관리형 설정](/docs/ko/server-managed-settings)과 macOS 관리형 환경설정 또는 Windows 레지스트리 정책의 변경 사항은 훅을 실행하지 않고 적용합니다. [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)가 적용된 WSL에서는 정책 폴링 시 변경된 Windows 측 관리형 설정 파일도 훅을 실행하지 않고 적용합니다.2926Claude Code는 설정 파일, 관리형 정책 파일 또는 스킬 파일이 변경될 때 ConfigChange 훅을 실행합니다. 관리형 정책의 경우 `managed-settings.json` 또는 `managed-settings.d/`의 파일이 변경될 때만 실행합니다. [서버 관리형 설정](/docs/ko/server-managed-settings)과 macOS 관리형 환경설정 또는 Windows 레지스트리 정책의 변경 사항은 훅을 실행하지 않고 적용합니다. [`wslInheritsWindowsSettings`](/docs/ko/settings-reference#wslinheritswindowssettings)를 사용하는 WSL에서는 변경된 Windows 측 관리형 설정 파일도 정책 폴링 시 훅을 실행하지 않고 적용합니다.
2921 2927
2922matcher는 구성 소스를 기준으로 필터링합니다.2928matcher는 구성 소스로 필터링합니다.
2923 2929
2924| Matcher | 발생 시점 |2930| Matcher | 발생 시점 |
2925| :- | :- |2931| :- | :- |
2950```2956```
2951 2957
2952<h4 id="configchange-input">2958<h4 id="configchange-input">
2953 ConfigChange 입력2959 ConfigChange input
2954</h4>2960</h4>
2955 2961
2956[공통 입력 필드](#common-input-fields) 외에도 ConfigChange 훅은 `source`와 선택적으로 `file_path`를 전달받습니다. `source` 필드는 어떤 구성 유형이 변경되었는지 나타내고, `file_path`는 수정된 특정 파일의 경로를 제공합니다.2962[공통 입력 필드](#common-input-fields) 외에도, ConfigChange 훅은 `source`와 선택적으로 `file_path`를 전달받습니다. `source` 필드는 어떤 구성 유형이 변경되었는지 나타내고, `file_path`는 수정된 특정 파일의 경로를 제공합니다.
2957 2963
2958```json theme={null}2964```json theme={null}
2959{2965{
2967```2973```
2968 2974
2969<h4 id="configchange-decision-control">2975<h4 id="configchange-decision-control">
2970 ConfigChange 결정 제어2976 ConfigChange decision control
2971</h4>2977</h4>
2972 2978
2973ConfigChange 훅은 구성 변경이 적용되지 않도록 차단할 수 있습니다. 변경을 막으려면 종료 코드 2 또는 JSON `decision`을 사용합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.2979ConfigChange 훅은 구성 변경이 적용되지 않도록 차단할 수 있습니다. 변경을 막으려면 종료 코드 2 또는 JSON `decision`을 사용합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.
2984}2990}
2985```2991```
2986 2992
2987`policy_settings` 변경은 차단할 수 없습니다. 머신의 관리형 설정 파일이 변경되면 `policy_settings` 소스에 대해서도 훅이 발생하므로 해당 편집을 로그에 기록하는 데 사용할 수 있지만, 차단 결정은 무시됩니다. 이를 통해 엔터프라이즈 관리형 설정이 항상 적용되도록 보장합니다. Claude Code는 [서버 관리형 설정](/docs/ko/server-managed-settings)이 도착하거나 새로 고쳐질 때 `ConfigChange` 훅을 실행하지 않습니다.2993`policy_settings` 변경은 차단할 수 없습니다. 머신의 관리형 설정 파일이 변경되면 `policy_settings` 소스에 대해서도 훅이 발생하므로 이러한 수정 사항을 로그에 기록하는 데 사용할 수 있지만, 차단 결정은 무시됩니다. 이를 통해 엔터프라이즈 관리형 설정이 항상 적용되도록 보장합니다. [서버 관리형 설정](/docs/ko/server-managed-settings)이 도착하거나 갱신될 때는 Claude Code가 `ConfigChange` 훅을 실행하지 않습니다.
2988 2994
2989Claude Code는 ConfigChange 훅의 JSON 출력에서 차단 결정에 따라 동작하며 `systemMessage`와 `continue`는 삭제합니다. 차단된 변경은 `reason`으로 차단하든 종료 코드 2의 stderr로 차단하든 사용자나 Claude에게 아무 메시지도 표시하지 않습니다. Claude Code는 디버그 로그에 한 줄만 기록합니다.2995Claude Code는 ConfigChange 훅의 JSON 출력에서 차단 결정에 따라 동작하며 `systemMessage`와 `continue`는 삭제합니다. `reason`으로 차단하든 종료 코드 2의 stderr로 차단하든, 차단된 변경은 사용자나 Claude에게 메시지를 표시하지 않습니다. Claude Code는 디버그 로그에 한 줄만 기록합니다.
2990 2996
2991<h3 id="cwdchanged">2997<h3 id="cwdchanged">
2992 CwdChanged2998 CwdChanged
2993</h3>2999</h3>
2994 3000
2995메인 대화의 셸 명령이 작업 디렉터리를 변경할 때 실행됩니다. 예를 들어 Claude가 `cd` 명령을 실행하는 경우입니다. 환경 변수 다시 로드, 프로젝트별 도구 체인 활성화, 설정 스크립트 자동 실행 등 디렉터리 변경에 대응하는 데 사용합니다. 디렉터리별 환경을 관리하는 [direnv](https://direnv.net/)와 같은 도구에는 [FileChanged](#filechanged)와 함께 사용합니다.3001메인 대화의 셸 명령이 작업 디렉터리를 변경할 때 실행됩니다. 예를 들어 Claude가 `cd` 명령을 실행할 때입니다. 디렉터리 변경에 대응하는 데 사용합니다. 환경 변수를 다시 로드하거나, 프로젝트별 툴체인을 활성화하거나, 설정 스크립트를 자동으로 실행할 수 있습니다. 디렉터리별 환경을 관리하는 [direnv](https://direnv.net/) 같은 도구를 위해 [FileChanged](#filechanged)와 함께 사용합니다.
2996 3002
2997CwdChanged 훅은 [`CLAUDE_ENV_FILE`](#persist-environment-variables)에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 CwdChanged 이벤트에서 Claude Code가 지울 때까지 이후의 Bash 명령에서 유지됩니다.3003CwdChanged 훅은 [`CLAUDE_ENV_FILE`](#persist-environment-variables)에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 CwdChanged 이벤트에서 Claude Code가 이를 지울 때까지 이후의 Bash 명령에 유지됩니다.
2998 3004
2999CwdChanged는 matcher를 지원하지 않으며 매번 발생합니다.3005CwdChanged는 matcher를 지원하지 않으며 매번 발생합니다.
3000 3006
3001<h4 id="cwdchanged-input">3007<h4 id="cwdchanged-input">
3002 CwdChanged 입력3008 CwdChanged input
3003</h4>3009</h4>
3004 3010
3005[공통 입력 필드](#common-input-fields) 외에도 CwdChanged 훅은 `old_cwd`와 `new_cwd`를 전달받습니다.3011[공통 입력 필드](#common-input-fields) 외에도, CwdChanged 훅은 `old_cwd`와 `new_cwd`를 전달받습니다.
3006 3012
3007```json theme={null}3013```json theme={null}
3008{3014{
3016```3022```
3017 3023
3018<h4 id="cwdchanged-output">3024<h4 id="cwdchanged-output">
3019 CwdChanged 출력3025 CwdChanged output
3020</h4>3026</h4>
3021 3027
3022모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 CwdChanged 훅은 [FileChanged](#filechanged)가 감시하는 파일 경로를 동적으로 설정하기 위해 `watchPaths`를 반환할 수 있습니다.3028모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도, CwdChanged 훅은 `watchPaths`를 반환하여 [FileChanged](#filechanged)가 감시하는 파일 경로를 동적으로 설정할 수 있습니다.
3023 3029
3024| 필드 | 설명 |3030| 필드 | 설명 |
3025| :- | :- |3031| :- | :- |
3026| `watchPaths` | 절대 경로 배열입니다. 현재 동적 감시 목록을 대체합니다. `matcher` 구성의 경로는 항상 감시됩니다. 빈 배열을 반환하면 동적 목록이 지워지며, 이는 새 디렉터리로 들어갈 때 일반적입니다 |3032| `watchPaths` | 절대 경로의 배열입니다. 현재 동적 감시 목록을 대체합니다. `matcher` 구성의 경로는 항상 감시됩니다. 빈 배열을 반환하면 동적 목록이 지워지며, 이는 새 디렉터리에 진입할 때 일반적입니다 |
3027 3033
3028CwdChanged 훅에는 결정 제어가 없습니다. 디렉터리 변경을 차단할 수 없습니다.3034CwdChanged 훅에는 결정 제어가 없습니다. 디렉터리 변경을 차단할 수 없습니다.
3029 3035
3030Claude Code는 JSON 출력에서 `watchPaths`와 `systemMessage`를 읽고 `continue`는 삭제합니다. 대화형 세션에서는 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 도달하지 않습니다.3036Claude Code는 JSON 출력에서 `watchPaths`와 `systemMessage`를 읽고 `continue`는 삭제합니다. 대화형 세션에서는 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 전달되지 않습니다.
3031 3037
3032<h3 id="directoryadded">3038<h3 id="directoryadded">
3033 DirectoryAdded3039 DirectoryAdded
3034</h3>3040</h3>
3035 3041
3036세션 중에 사용자가 `/add-dir` 명령으로 작업 디렉터리를 추가한 후, 또는 SDK 클라이언트가 `register_repo_root` 제어 요청으로 작업 디렉터리를 추가한 후에 실행됩니다. 예를 들어 의존성을 설치하는 등 새로 추가된 저장소를 준비하는 데 사용합니다.3042세션 중에 사용자가 `/add-dir` 명령으로 작업 디렉터리를 추가한 후, 또는 SDK 클라이언트가 `register_repo_root` 제어 요청으로 작업 디렉터리를 추가한 후에 실행됩니다. 예를 들어 의존성을 설치하는 것처럼 새로 추가된 저장소를 준비하는 데 사용합니다.
3037 3043
3038Claude Code는 다음 경우에 이 이벤트를 발생시키지 않습니다.3044Claude Code는 다음 경우에 이 이벤트를 발생시키지 않습니다.
3039 3045
3040* `--add-dir` 시작 플래그로 디렉터리를 전달하는 경우. 이러한 디렉터리는 [SessionStart](#sessionstart)에서 다룹니다3046* `--add-dir` 시작 플래그로 디렉터리를 전달한 경우. 이러한 디렉터리는 [SessionStart](#sessionstart)가 처리합니다
3041* `/permissions` Workspace 탭에서 디렉터리를 추가하는 경우3047* `/permissions`의 Workspace 탭에서 디렉터리를 추가한 경우
3042* 이미 작업 디렉터리이거나 작업 디렉터리 내부에 있는 디렉터리를 추가하는 경우3048* 이미 작업 디렉터리이거나 작업 디렉터리 내부에 있는 디렉터리를 추가한 경우
3043 3049
3044Claude Code는 샌드박스 및 권한 상태를 새로 고친 후 DirectoryAdded를 발생시키므로, 훅이 실행될 때 샌드박스 처리된 도구는 이미 새 디렉터리를 인식합니다. 훅 명령 자체는 샌드박스 없이 실행됩니다.3050Claude Code는 샌드박스 및 권한 상태를 갱신한 후 DirectoryAdded를 발생시키므로, 훅이 실행될 때 샌드박스 처리된 도구는 이미 새 디렉터리를 인식합니다. 훅 명령 자체는 샌드박스 없이 실행됩니다.
3045 3051
3046Claude Code는 훅을 기다리지 않습니다. 추가는 즉시 완료되며, 훅은 600초 기본 타임아웃으로 백그라운드에서 실행됩니다.3052Claude Code는 훅을 기다리지 않습니다. 추가는 즉시 완료되며, 훅은 600초의 기본 타임아웃으로 백그라운드에서 실행됩니다.
3047 3053
3048matcher는 디렉터리가 추가된 방식을 기준으로 필터링합니다.3054matcher는 디렉터리가 추가된 방식으로 필터링합니다.
3049 3055
3050| Matcher | 발생 시점 |3056| Matcher | 발생 시점 |
3051| :- | :- |3057| :- | :- |
3052| `slash_command` | `/add-dir`로 디렉터리를 추가한 경우 |3058| `slash_command` | 사용자가 `/add-dir`로 디렉터리를 추가한 경우 |
3053| `register_repo_root` | SDK 클라이언트가 `register_repo_root` 제어 요청으로 디렉터리를 추가한 경우 |3059| `register_repo_root` | SDK 클라이언트가 `register_repo_root` 제어 요청으로 디렉터리를 추가한 경우 |
3054 3060
3055<h4 id="directoryadded-input">3061<h4 id="directoryadded-input">
3056 DirectoryAdded 입력3062 DirectoryAdded input
3057</h4>3063</h4>
3058 3064
3059[공통 입력 필드](#common-input-fields) 외에도 DirectoryAdded 훅은 `directory`와 `source`를 전달받습니다.3065[공통 입력 필드](#common-input-fields) 외에도, DirectoryAdded 훅은 `directory`와 `source`를 전달받습니다.
3060 3066
3061| 필드 | 설명 |3067| 필드 | 설명 |
3062| :- | :- |3068| :- | :- |
3063| `directory` | 추가된 디렉터리의 절대 경로입니다 |3069| `directory` | 추가된 디렉터리의 절대 경로입니다 |
3064| `source` | 디렉터리가 추가된 방식이며, `/add-dir`의 경우 `"slash_command"`, SDK 제어 요청의 경우 `"register_repo_root"`입니다 |3070| `source` | 디렉터리가 추가된 방식으로, `/add-dir`의 경우 `"slash_command"`, SDK 제어 요청의 경우 `"register_repo_root"`입니다 |
3065 3071
3066```json theme={null}3072```json theme={null}
3067{3073{
3074}3080}
3075```3081```
3076 3082
3077DirectoryAdded 훅에는 결정 제어가 없습니다. 훅이 실행될 때 이미 완료된 추가를 차단할 수 없습니다. Claude Code는 JSON 출력에서 `continue` 필드를 삭제하고 나머지는 소스에 따라 다르게 표시합니다.3083DirectoryAdded 훅에는 결정 제어가 없습니다. 훅이 실행될 때 이미 완료된 추가를 차단할 수 없습니다. Claude Code는 JSON 출력에서 `continue` 필드를 삭제하고, 나머지는 소스에 따라 다르게 표시합니다.
3078 3084
3079* `slash_command`: Claude Code는 훅의 `systemMessage`를 사용자에게 표시하는 대신 다음 대화 턴에서 Claude에게 컨텍스트로 전달합니다. 실패한 훅의 개수가 트랜스크립트에 표시됩니다. 전체 실패 출력은 디버그 로그에 기록됩니다3085* `slash_command`: Claude Code는 훅의 `systemMessage`를 사용자에게 표시하는 대신 다음 대화 턴에서 Claude에 컨텍스트로 전달합니다. 실패한 훅의 수가 트랜스크립트에 표시됩니다. 전체 실패 출력은 디버그 로그에 기록됩니다
3080* `register_repo_root`: Claude Code는 `systemMessage` 출력과 실패 출력을 디버그 로그에만 기록합니다3086* `register_repo_root`: Claude Code는 `systemMessage` 출력과 실패 출력을 디버그 로그에만 기록합니다
3081 3087
3082<h3 id="filechanged">3088<h3 id="filechanged">
3083 FileChanged3089 FileChanged
3084</h3>3090</h3>
3085 3091
3086감시 중인 파일이 디스크에서 변경될 때 실행됩니다. Claude Code는 도구 호출을 검사하는 것이 아니라 파일 시스템 감시자로 변경을 감지하므로, `Edit` 또는 `Write` 도구 호출, Claude가 `Bash`로 실행하는 스크립트, Claude Code 외부의 프로세스 등 무엇이 파일을 변경했는지와 관계없이 훅을 실행합니다. 일반적인 용도는 프로젝트 설정 파일이 변경될 때 환경 변수를 다시 로드하는 것입니다.3092감시 중인 파일이 디스크에서 변경될 때 실행됩니다. Claude Code는 도구 호출을 검사하는 것이 아니라 파일 시스템 감시자로 변경을 감지하므로, 무엇이 파일을 변경했든 훅을 실행합니다. `Edit` 또는 `Write` 도구 호출, Claude가 `Bash`로 실행하는 스크립트, 또는 Claude Code 외부의 프로세스 모두 해당됩니다. 일반적인 용도는 프로젝트 설정 파일이 변경될 때 환경 변수를 다시 로드하는 것입니다.
3087 3093
3088이 이벤트의 `matcher`는 두 가지 역할을 합니다.3094이 이벤트의 `matcher`는 두 가지 역할을 합니다.
3089 3095
3090* **감시 목록 구성**: 값은 `|`를 기준으로 분할되며 각 세그먼트는 작업 디렉터리의 리터럴 파일 이름으로 등록되므로, `".envrc|.env"`는 정확히 이 두 파일을 감시합니다. 여기서는 정규식 패턴이 유용하지 않습니다. `^\.env`와 같은 값은 문자 그대로 `^\.env`라는 이름의 파일을 감시합니다.3096* **감시 목록 구성**: 값을 `|`로 분할하고 각 세그먼트를 작업 디렉터리의 리터럴 파일 이름으로 등록하므로, `".envrc|.env"`는 정확히 이 두 파일을 감시합니다. 여기서는 정규식 패턴이 유용하지 않습니다. `^\.env` 같은 값은 문자 그대로 `^\.env`라는 이름의 파일을 감시합니다.
3091* **실행할 훅 필터링**: 감시 중인 파일이 변경되면 같은 값이 변경된 파일의 basename에 대해 표준 [matcher 규칙](#matcher-patterns)을 사용하여 실행할 훅 그룹을 필터링합니다.3097* **실행할 훅 필터링**: 감시 중인 파일이 변경되면, 같은 값이 표준 [matcher 규칙](#matcher-patterns)을 사용하여 변경된 파일의 기본 이름(basename)을 대상으로 실행할 훅 그룹을 필터링합니다.
3092 3098
3093이 예시는 `Bash` 명령이나 외부 스크립트가 파일을 다시 쓰는 경우를 포함하여 `data.csv`가 변경될 때마다 줄 바꿈 문자를 정규화합니다.3099이 예시는 `Bash` 명령이나 외부 스크립트가 파일을 다시 쓰는 경우를 포함하여, 모든 변경 후 `data.csv`의 줄 끝을 정규화합니다.
3094 3100
3095```json theme={null}3101```json theme={null}
3096{3102{
3110}3116}
3111```3117```
3112 3118
3113훅은 stdin의 [JSON 입력](#filechanged-input)에 있는 `file_path` 필드에서 변경된 파일의 절대 경로를 읽습니다. 훅의 `grep` 가드는 `perl`이 제거하는 것과 같은 대상, 즉 줄 끝의 CR을 검사하므로 정규화 이후의 실행은 파일을 건드리지 않고 종료됩니다. 가드가 더 느슨하면 무한 루프가 발생합니다. `perl -i`는 아무것도 치환하지 않더라도 파일을 다시 쓰고, Claude Code는 파일을 다시 쓸 때마다 훅을 다시 실행하기 때문입니다. 이 스크립트를 `/path/to/normalize-line-endings.sh`에 저장하고 실행 가능하게 만듭니다.3119훅은 stdin의 [JSON 입력](#filechanged-input)에 있는 `file_path` 필드에서 변경된 파일의 절대 경로를 읽습니다. `grep` 가드는 `perl`이 제거하는 것과 같은 대상, 즉 줄 끝의 CR을 검사하므로, 정규화 이후의 실행은 파일을 건드리지 않고 종료됩니다. 더 느슨한 가드는 무한 루프에 빠집니다. `perl -i`는 치환할 것이 없어도 파일을 다시 쓰고, Claude Code는 다시 쓸 때마다 훅을 다시 실행하기 때문입니다. 이 스크립트를 `/path/to/normalize-line-endings.sh`에 저장하고 실행 가능하게 만듭니다.
3114 3120
3115```bash theme={null}3121```bash theme={null}
3116#!/bin/bash3122#!/bin/bash
3120fi3126fi
3121```3127```
3122 3128
3123훅이 작동하는지 확인하려면 Claude에게 `Bash` 명령으로 `data.csv`에 CRLF 줄을 추가하도록 요청합니다. Claude Code가 훅을 실행하면 파일의 줄 바꿈이 LF로 바뀝니다.3129훅이 작동하는지 확인하려면 Claude에 `Bash` 명령으로 `data.csv`에 CRLF 줄을 추가하도록 요청합니다. Claude Code가 훅을 실행하고 파일은 LF 줄 끝을 갖게 됩니다.
3124 3130
3125미리 이름을 지정할 수 없는 파일을 감시하려면 훅에서 [`watchPaths`](#filechanged-output)를 반환하여 감시 목록을 동적으로 업데이트합니다. Claude Code는 감시할 파일이 지정된 경우에만 감시자를 시작하므로, matcher에 하나 이상의 파일 이름을 지정한 FileChanged 그룹이나 `watchPaths`를 반환하는 [SessionStart](#sessionstart-decision-control) 또는 [CwdChanged](#cwdchanged) 훅으로 목록을 초기화합니다. 감시 중인 파일이 변경될 때 matcher는 여전히 실행할 훅 그룹을 필터링하므로, 동적 경로를 처리하는 그룹에는 matcher를 생략합니다. matcher를 생략하면 감시 중인 모든 파일과 매칭되며 감시 목록에는 아무것도 추가되지 않습니다. `"*"` matcher도 모든 파일과 매칭되지만, Claude Code는 이를 다른 값과 마찬가지로 `*`라는 이름의 리터럴 파일로 감시 목록에 등록합니다.3131미리 이름을 지정할 수 없는 파일을 감시하려면 훅에서 [`watchPaths`](#filechanged-output)를 반환하여 감시 목록을 동적으로 업데이트합니다. Claude Code는 감시할 파일이 지정될 때만 감시자를 시작하므로, matcher가 최소 하나의 파일을 지정하는 FileChanged 그룹이나 `watchPaths`를 반환하는 [SessionStart](#sessionstart-decision-control) 또는 [CwdChanged](#cwdchanged) 훅으로 목록을 초기화합니다. matcher는 감시 중인 파일이 변경될 때 실행할 훅 그룹을 여전히 필터링하므로, 동적 경로를 처리하는 그룹에는 matcher를 생략합니다. 생략된 matcher는 모든 감시 파일과 매칭되며 감시 목록에 아무것도 추가하지 않습니다. `"*"` matcher도 모든 파일과 매칭되지만, Claude Code는 이를 다른 값과 마찬가지로 `*`라는 이름의 리터럴 파일로 감시 목록에 등록합니다.
3126 3132
3127FileChanged 훅은 [`CLAUDE_ENV_FILE`](#persist-environment-variables)에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 [CwdChanged](#cwdchanged) 이벤트에서 Claude Code가 지울 때까지 이후의 Bash 명령에서 유지됩니다.3133FileChanged 훅은 [`CLAUDE_ENV_FILE`](#persist-environment-variables)에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 [CwdChanged](#cwdchanged) 이벤트에서 Claude Code가 이를 지울 때까지 이후의 Bash 명령에 유지됩니다.
3128 3134
3129<h4 id="filechanged-input">3135<h4 id="filechanged-input">
3130 FileChanged 입력3136 FileChanged input
3131</h4>3137</h4>
3132 3138
3133[공통 입력 필드](#common-input-fields) 외에도 FileChanged 훅은 `file_path`와 `event`를 전달받습니다.3139[공통 입력 필드](#common-input-fields) 외에도, FileChanged 훅은 `file_path`와 `event`를 전달받습니다.
3134 3140
3135| 필드 | 설명 |3141| 필드 | 설명 |
3136| :- | :- |3142| :- | :- |
3149```3155```
3150 3156
3151<h4 id="filechanged-output">3157<h4 id="filechanged-output">
3152 FileChanged 출력3158 FileChanged output
3153</h4>3159</h4>
3154 3160
3155모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 FileChanged 훅은 감시할 파일 경로를 동적으로 업데이트하기 위해 `watchPaths`를 반환할 수 있습니다.3161모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도, FileChanged 훅은 `watchPaths`를 반환하여 감시할 파일 경로를 동적으로 업데이트할 수 있습니다.
3156 3162
3157| 필드 | 설명 |3163| 필드 | 설명 |
3158| :- | :- |3164| :- | :- |
3159| `watchPaths` | 절대 경로 배열입니다. 현재 동적 감시 목록을 대체합니다. `matcher` 구성의 경로는 항상 감시됩니다. 훅 스크립트가 변경된 파일을 기반으로 감시할 추가 파일을 발견한 경우에 사용합니다 |3165| `watchPaths` | 절대 경로의 배열입니다. 현재 동적 감시 목록을 대체합니다. `matcher` 구성의 경로는 항상 감시됩니다. 훅 스크립트가 변경된 파일을 기반으로 감시할 추가 파일을 찾았을 때 사용합니다 |
3160 3166
3161FileChanged 훅에는 결정 제어가 없습니다. 파일 변경이 발생하는 것을 차단할 수 없습니다.3167FileChanged 훅에는 결정 제어가 없습니다. 파일 변경이 일어나는 것을 차단할 수 없습니다.
3162 3168
3163Claude Code는 JSON 출력에서 `watchPaths`와 `systemMessage`를 읽고 `continue`는 삭제합니다. 대화형 세션에서는 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 도달하지 않습니다.3169Claude Code는 JSON 출력에서 `watchPaths`와 `systemMessage`를 읽고 `continue`는 삭제합니다. 대화형 세션에서는 `systemMessage`를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 전달되지 않습니다.
3164 3170
3165<h3 id="worktreecreate">3171<h3 id="worktreecreate">
3166 WorktreeCreate3172 WorktreeCreate
3167</h3>3173</h3>
3168 3174
3169`claude --worktree`, [`isolation: "worktree"`를 사용하는 서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope), 또는 Claude Code가 자체 워크트리에 격리하는 [백그라운드 세션](/docs/ko/agent-view#how-file-edits-are-isolated) 등에서 워크트리가 생성될 때 실행됩니다. 기본적으로 Claude Code는 `git worktree`로 격리된 작업 사본을 만듭니다. WorktreeCreate 훅을 구성하면 이 기본 git 동작이 대체되므로 SVN, Perforce, Mercurial과 같은 다른 버전 관리 시스템을 사용할 수 있습니다.3175`claude --worktree`, [`isolation: "worktree"`를 사용하는 서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope), 또는 Claude Code가 자체 worktree에 격리하는 [백그라운드 세션](/docs/ko/agent-view#how-file-edits-are-isolated) 등으로 worktree가 생성될 때 실행됩니다. 기본적으로 Claude Code는 `git worktree`로 격리된 작업 사본을 생성합니다. WorktreeCreate 훅을 구성하면 이 기본 git 동작이 대체되므로, SVN, Perforce, Mercurial 같은 다른 버전 관리 시스템을 사용할 수 있습니다.
3170 3176
3171훅이 기본 동작을 완전히 대체하므로 [`.worktreeinclude`](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)는 처리되지 않습니다. `.env`와 같은 로컬 설정 파일을 새 워크트리에 복사해야 한다면 훅 스크립트 내부에서 수행합니다.3177훅이 기본 동작을 완전히 대체하므로 [`.worktreeinclude`](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)는 처리되지 않습니다. `.env` 같은 로컬 설정 파일을 새 워크트리에 복사해야 하는 경우 훅 스크립트 안에서 수행합니다.
3172 3178
3173훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다. Claude Code는 이 경로를 격리된 세션의 작업 디렉터리로 사용합니다. 각 훅 유형이 경로를 반환하는 방법은 [WorktreeCreate 출력](#worktreecreate-output)을 참조하세요.3179훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다. Claude Code는 이 경로를 격리된 세션의 작업 디렉터리로 사용합니다. 각 훅 유형이 경로를 반환하는 방법은 [WorktreeCreate 출력](#worktreecreate-output)을 참조하세요.
3174 3180
3175Claude Code는 훅의 성공 여부와 반환된 경로에 따라 동작하며, `systemMessage`와 `continue`는 삭제합니다.3181Claude Code는 훅의 성공 여부와 반환된 경로에 따라 동작하며, `systemMessage`와 `continue`는 삭제합니다.
3176 3182
3177이 예시는 SVN 작업 사본을 만들고 Claude Code가 사용할 경로를 출력합니다. 저장소 URL을 자신의 것으로 바꾸세요.3183이 예시는 SVN 작업 사본을 생성하고 Claude Code가 사용할 경로를 출력합니다. 저장소 URL을 자신의 것으로 바꿉니다.
3178 3184
3179```json theme={null}3185```json theme={null}
3180{3186{
3193}3199}
3194```3200```
3195 3201
3196훅은 stdin의 JSON 입력에서 worktree `name`을 읽고, 새 디렉터리에 새 사본을 체크아웃한 다음, 디렉터리 경로를 출력합니다. 마지막 줄의 `echo`가 Claude Code가 worktree 경로로 읽는 부분입니다. 경로에 간섭하지 않도록 다른 모든 출력은 stderr로 리디렉션합니다.3202훅은 stdin의 JSON 입력에서 worktree `name`을 읽고, 새 디렉터리에 새 사본을 체크아웃한 다음, 디렉터리 경로를 출력합니다. 마지막 줄의 `echo`가 Claude Code가 worktree 경로로 읽는 부분입니다. 경로에 방해가 되지 않도록 다른 모든 출력은 stderr로 리디렉션합니다.
3197 3203
3198<h4 id="worktreecreate-input">3204<h4 id="worktreecreate-input">
3199 WorktreeCreate 입력3205 WorktreeCreate input
3200</h4>3206</h4>
3201 3207
3202[공통 입력 필드](#common-input-fields) 외에도 WorktreeCreate 훅은 `name` 필드를 전달받습니다. 이는 새 워크트리의 슬러그 식별자로, 사용자가 지정하거나 자동 생성되며 예를 들면 `bold-oak-a3f2`와 같습니다.3208[공통 입력 필드](#common-input-fields) 외에도, WorktreeCreate 훅은 `name` 필드를 전달받습니다. 이는 사용자가 지정하거나 자동 생성된 새 worktree의 슬러그 식별자로, 예를 들면 `bold-oak-a3f2`입니다.
3203 3209
3204```json theme={null}3210```json theme={null}
3205{3211{
3217 3223
3218WorktreeCreate 훅은 표준 허용/차단 결정 모델을 사용하지 않습니다. 대신 훅의 성공 또는 실패가 결과를 결정합니다. 훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다.3224WorktreeCreate 훅은 표준 허용/차단 결정 모델을 사용하지 않습니다. 대신 훅의 성공 또는 실패가 결과를 결정합니다. 훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다.
3219 3225
3220* **명령 훅** (`type: "command"`): 경로를 stdout의 마지막 비어 있지 않은 줄로 출력합니다. Claude Code는 해당 줄을 읽기 전에 ANSI 이스케이프 코드를 제거하므로 `echo` 전에 출력된 셸 시작 배너는 무시됩니다. 그 밖의 훅 출력은 stderr로 리디렉션합니다.3226* **명령 훅** (`type: "command"`): stdout의 비어 있지 않은 마지막 줄에 경로를 출력합니다. Claude Code는 해당 줄을 읽기 전에 ANSI 이스케이프 코드를 제거하므로 `echo` 이전에 출력된 셸 시작 배너는 무시됩니다. 그 밖의 훅 출력은 stderr로 리디렉션하십시오.
3221* **HTTP 훅** (`type: "http"`): 응답 본문에 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`를 반환합니다.3227* **HTTP 훅** (`type: "http"`): 응답 본문에 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`를 반환합니다.
3222 3228
3223훅이 실패하거나 경로를 생성하지 않으면 worktree 생성이 오류와 함께 실패합니다.3229훅이 실패하거나 경로를 생성하지 않으면 worktree 생성이 오류와 함께 실패합니다.
3224 3230
3225Claude Code는 상대 경로를 훅이 실행된 디렉터리를 기준으로 해석하며, 경로에 포함된 `.` 또는 `..` 세그먼트를 정리합니다. 결과 경로가 Claude Code가 진입할 수 있는 디렉터리가 아니면 세션은 해당 경로를 명시한 오류를 출력하고 코드 1로 종료합니다.3231Claude Code는 상대 경로를 훅이 실행된 디렉터리를 기준으로 해석하며, 경로에 포함된 `.` 또는 `..` 세그먼트를 정리합니다. 결과 경로가 Claude Code가 진입할 수 있는 디렉터리가 아니면 세션은 해당 경로를 명시한 오류를 출력하고 코드 1로 종료됩니다.
3226 3232
3227Claude Code는 `.` 또는 `..` 세그먼트를 포함하는 절대 경로와 저장소 루트 아래의 심볼릭 링크를 통과하는 모든 경로를 거부합니다. 저장소에 커밋된 심볼릭 링크가 worktree를 저장소 외부로 리디렉션할 수 있기 때문입니다. 오류에는 거부된 구성 요소가 명시됩니다. 저장소 내부의 심볼릭 링크를 통과하지 않는 정규화된 경로를 반환해야 합니다. v2.1.216 이전에는 worktree 생성 시 이러한 검사 없이 훅의 경로를 그대로 따랐습니다.3233Claude Code는 `.` 또는 `..` 세그먼트가 포함된 절대 경로와 저장소 루트 아래의 심볼릭 링크를 거치는 모든 경로를 거부합니다. 저장소에 커밋된 심볼릭 링크가 워크트리를 저장소 외부로 리디렉션할 수 있기 때문입니다. 오류 메시지에는 거부된 구성 요소가 명시됩니다. 저장소 내부의 심볼릭 링크를 거치지 않는 정규화된 경로를 반환하십시오. v2.1.216 이전에는 worktree 생성 시 이러한 검사 없이 훅의 경로를 그대로 따랐습니다.
3228 3234
3229<h3 id="worktreeremove">3235<h3 id="worktreeremove">
3230 WorktreeRemove3236 WorktreeRemove
3231</h3>3237</h3>
3232 3238
3233worktree가 제거될 때 실행됩니다. [WorktreeCreate](#worktreecreate)에 대응하는 정리용 이벤트입니다. 이 이벤트는 다음과 같은 경우에 발생합니다.3239worktree가 제거될 때 실행됩니다. [WorktreeCreate](#worktreecreate)에 대응하는 정리용 이벤트입니다. 이 이벤트는 다음 경우에 발생합니다.
3234 3240
3235* `--worktree` 세션을 종료하면서 제거를 선택한 경우3241* `--worktree` 세션을 종료하면서 제거를 선택한 경우
3236* `isolation: "worktree"`가 설정된 서브에이전트가 완료된 경우3242* `isolation: "worktree"`가 설정된 서브에이전트가 완료된 경우
3237* 훅이 생성한 worktree를 사용하는 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제한 경우3243* 훅이 생성한 worktree를 사용하는 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제한 경우
3238 3244
3239git 기반 worktree의 경우 Claude Code가 `git worktree remove`로 정리를 자동 처리합니다. WorktreeCreate 훅을 구성했다면 WorktreeRemove 훅과 함께 사용하여 해당 훅이 생성한 worktree의 정리를 제어하십시오.3245git 기반 worktree의 경우 Claude Code가 `git worktree remove`로 정리를 자동으로 처리합니다. WorktreeCreate 훅을 구성했다면 WorktreeRemove 훅과 함께 사용하여 해당 훅이 생성한 워크트리의 정리를 제어하십시오.
3240 3246
3241* **WorktreeRemove 훅이 없는 경우**: `--worktree` 세션을 종료하면서 제거를 선택하면 Claude Code는 WorktreeCreate 훅이 반환한 경로에 대해 `git worktree remove --force`로 폴백하므로, git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 worktree(예: 훅이 git 이외의 버전 관리 시스템으로 생성한 worktree)는 디스크에 남습니다. [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제할 때 훅이 생성한 worktree가 어떻게 처리되는지는 에이전트 뷰의 삭제 규칙을 참조하십시오.3247* **WorktreeRemove 훅이 없는 경우**: `--worktree` 세션을 종료하면서 제거를 선택하면 Claude Code는 WorktreeCreate 훅이 반환한 경로에 대해 `git worktree remove --force`로 폴백하므로, git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 워크트리(예: 훅이 git이 아닌 버전 관리 시스템으로 생성한 워크트리)는 디스크에 남습니다. [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제할 때 훅이 생성한 워크트리가 어떻게 처리되는지는 에이전트 뷰의 삭제 규칙을 참조하십시오.
3242* **훅이 0으로 종료하는 경우**: worktree가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 정보를 읽지 않으므로 훅이 디렉터리를 실제로 삭제했는지 확인해야 합니다.3248* **훅이 0으로 종료되는 경우**: 워크트리가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 내용을 읽지 않으므로 훅이 디렉터리를 실제로 삭제했는지 확인하십시오.
3243* **훅이 0이 아닌 코드로 종료하는 경우**: 이후에도 `worktree_path`의 디렉터리가 존재하면 제거가 실패하며, worktree는 git 폴백 없이 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 [WorktreeRemove 입력](#worktreeremove-input)을 참조하십시오.3249* **훅이 0이 아닌 코드로 종료되는 경우**: 이후에도 `worktree_path`의 디렉터리가 여전히 존재하면 제거가 실패하고, 워크트리는 git 폴백 없이 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 [WorktreeRemove 입력](#worktreeremove-input)을 참조하십시오.
3244 3250
3245Claude Code는 WorktreeCreate 훅이 반환한 경로만 알기 때문에 훅이 생성한 worktree에 속한 브랜치를 삭제하지 않습니다. WorktreeCreate 훅이 브랜치를 생성한다면 WorktreeRemove 훅에서 해당 브랜치를 삭제하십시오.3251Claude Code는 WorktreeCreate 훅이 반환한 경로만 알기 때문에 훅이 생성한 워크트리에 속한 브랜치를 삭제하지 않습니다. WorktreeCreate 훅이 브랜치를 생성한다면 WorktreeRemove 훅에서 해당 브랜치를 삭제하십시오.
3246 3252
3247Claude Code는 WorktreeRemove 훅의 `systemMessage`, `continue` 등 [JSON 출력 필드](#json-output)를 무시합니다.3253Claude Code는 `systemMessage`, `continue` 등 WorktreeRemove 훅의 [JSON 출력 필드](#json-output)를 폐기합니다.
3248 3254
3249백그라운드 세션 삭제 시 Claude Code는 훅을 실행하기 전에 저장된 worktree 경로를 검증하며, 심볼릭 링크이거나 저장소 루트 아래의 심볼릭 링크를 통과하는 경로는 거부합니다. 아직 파일이 남아 있는 worktree에 대해서는 [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)에서 삭제를 확인한 경우에만 훅이 실행됩니다. 이러한 worktree의 경우 [`claude rm`](/docs/ko/agent-view#manage-sessions-from-the-shell)은 세션과 worktree를 그대로 유지합니다. v2.1.216 이전에는 이러한 검사 없이 저장된 경로에 대해 훅이 실행되었습니다.3255백그라운드 세션 삭제 시 Claude Code는 훅을 실행하기 전에 저장된 worktree 경로를 검증하며, 심볼릭 링크이거나 저장소 루트 아래의 심볼릭 링크를 거치는 경로를 거부합니다. 파일이 아직 남아 있는 워크트리에 대해서는 [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)에서 삭제를 확인한 경우에만 훅이 실행되며, 이러한 워크트리에 대해 [`claude rm`](/docs/ko/agent-view#manage-sessions-from-the-shell)은 세션과 워크트리를 그대로 유지합니다. v2.1.216 이전에는 이러한 검사 없이 저장된 경로에 대해 훅이 실행되었습니다.
3250 3256
3251Claude Code는 WorktreeCreate가 반환한 경로를 훅 입력의 `worktree_path`로 전달합니다. 다음 예시는 해당 경로를 읽어 디렉터리를 제거합니다.3257Claude Code는 WorktreeCreate가 반환한 경로를 훅 입력의 `worktree_path`로 전달합니다. 다음 예시는 해당 경로를 읽어 디렉터리를 제거합니다.
3252 3258
3271 WorktreeRemove 입력3277 WorktreeRemove 입력
3272</h4>3278</h4>
3273 3279
3274[공통 입력 필드](#common-input-fields) 외에도 WorktreeRemove 훅은 제거되는 worktree의 절대 경로인 `worktree_path` 필드를 받습니다.3280[공통 입력 필드](#common-input-fields)에 더해 WorktreeRemove 훅은 제거되는 worktree의 절대 경로인 `worktree_path` 필드를 받습니다.
3275 3281
3276```json theme={null}3282```json theme={null}
3277{3283{
3283}3289}
3284```3290```
3285 3291
3286WorktreeRemove 훅의 종료 코드가 결과를 결정합니다. 훅이 0이 아닌 코드로 종료하고 이후에도 `worktree_path`의 디렉터리가 존재하면 제거가 실패합니다.3292WorktreeRemove 훅의 종료 코드가 결과를 결정합니다. 훅이 0이 아닌 코드로 종료되고 이후에도 `worktree_path`의 디렉터리가 여전히 존재하면 제거가 실패합니다.
3287 3293
3288* worktree는 디스크에 남으며, 훅의 명령과 stderr는 [디버그 로그](#debug-hooks)에 기록됩니다.3294* 워크트리는 디스크에 남고, 훅의 명령과 stderr는 [디버그 로그](#debug-hooks)에 기록됩니다.
3289* 백그라운드 세션을 삭제하던 중이었다면 세션도 유지됩니다. [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)의 거부 메시지는 `exited 1`과 같이 훅이 어떻게 종료되었는지 보고하고, stderr의 앞부분을 인용하며, 세션을 다시 삭제하면 디렉터리가 어쨌든 제거되는지 여부를 알려 줍니다.3295* 백그라운드 세션을 삭제하던 중이었다면 세션도 유지됩니다. [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)의 거부 메시지는 `exited 1`과 같이 훅이 어떻게 종료되었는지 보고하고, stderr의 앞부분을 인용하며, 세션을 다시 삭제하면 디렉터리가 그래도 제거되는지 여부를 알려줍니다.
3290 3296
3291<h3 id="precompact">3297<h3 id="precompact">
3292 PreCompact3298 PreCompact
3296 3302
3297matcher 값은 압축이 수동으로 트리거되었는지 자동으로 트리거되었는지를 나타냅니다.3303matcher 값은 압축이 수동으로 트리거되었는지 자동으로 트리거되었는지를 나타냅니다.
3298 3304
3299| Matcher | 발생 시점 |3305| Matcher | 실행 시점 |
3300| :- | :- |3306| :- | :- |
3301| `manual` | `/compact` |3307| `manual` | `/compact` |
3302| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달하여 자동 압축될 때 |3308| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달하여 자동 압축될 때 |
3303 3309
3304압축을 차단하려면 코드 2로 종료합니다. 수동 `/compact`의 경우 stderr 메시지가 사용자에게 표시됩니다. `"decision": "block"`이 포함된 JSON을 반환하여 차단할 수도 있습니다.3310압축을 차단하려면 코드 2로 종료하십시오. 수동 `/compact`의 경우 stderr 메시지가 사용자에게 표시됩니다. `"decision": "block"`이 포함된 JSON을 반환하여 차단할 수도 있습니다.
3305 3311
3306자동 압축을 차단하면 발생 시점에 따라 효과가 다릅니다. 컨텍스트 한도에 도달하기 전에 선제적으로 압축이 트리거된 경우 Claude Code는 압축을 건너뛰고 압축되지 않은 상태로 대화를 계속합니다. API가 이미 반환한 컨텍스트 한도 오류에서 복구하기 위해 압축이 트리거된 경우에는 원래 오류가 표시되고 현재 요청이 실패합니다.3312자동 압축을 차단하면 실행 시점에 따라 효과가 달라집니다. 컨텍스트 한도에 도달하기 전에 선제적으로 압축이 트리거된 경우 Claude Code는 압축을 건너뛰고 대화는 압축되지 않은 상태로 계속됩니다. API가 이미 반환한 컨텍스트 한도 오류에서 복구하기 위해 압축이 트리거된 경우에는 원래 오류가 드러나고 현재 요청이 실패합니다.
3307 3313
3308Claude Code는 PreCompact 훅의 `systemMessage` 및 `continue` 필드를 무시합니다.3314Claude Code는 PreCompact 훅의 `systemMessage` 및 `continue` 필드를 폐기합니다.
3309 3315
3310<h4 id="precompact-input">3316<h4 id="precompact-input">
3311 PreCompact 입력3317 PreCompact 입력
3312</h4>3318</h4>
3313 3319
3314[공통 입력 필드](#common-input-fields) 외에도 PreCompact 훅은 `trigger`와 `custom_instructions`를 받습니다. `manual`의 경우 `custom_instructions`에는 사용자가 `/compact`에 전달한 내용이 담기며, 아무것도 전달하지 않으면 `null`입니다. `auto`의 경우 `custom_instructions`는 `null`입니다.3320[공통 입력 필드](#common-input-fields)에 더해 PreCompact 훅은 `trigger`와 `custom_instructions`를 받습니다. `manual`의 경우 `custom_instructions`에는 사용자가 `/compact`에 전달한 내용이 담기며, 아무것도 전달하지 않으면 `null`입니다. `auto`의 경우 `custom_instructions`는 `null`입니다.
3315 3321
3316```json theme={null}3322```json theme={null}
3317{3323{
3328 PostCompact3334 PostCompact
3329</h3>3335</h3>
3330 3336
3331Claude Code가 압축 작업을 완료한 후 실행됩니다. 이 이벤트를 사용하여 새로 압축된 상태에 대응할 수 있습니다. 예를 들어 생성된 요약을 로그에 기록하거나 외부 상태를 업데이트할 수 있습니다. Claude Code는 PostCompact 훅의 `systemMessage` 및 `continue` 필드를 무시합니다.3337Claude Code가 압축 작업을 완료한 후 실행됩니다. 새로 압축된 상태에 대응할 때 이 이벤트를 사용하십시오. 예를 들어 생성된 요약을 로그에 기록하거나 외부 상태를 업데이트할 수 있습니다. Claude Code는 PostCompact 훅의 `systemMessage` 및 `continue` 필드를 폐기합니다.
3332 3338
3333`PreCompact`와 동일한 matcher 값이 적용됩니다.3339`PreCompact`와 동일한 matcher 값이 적용됩니다.
3334 3340
3335| Matcher | 발생 시점 |3341| Matcher | 실행 시점 |
3336| :- | :- |3342| :- | :- |
3337| `manual` | `/compact` 이후 |3343| `manual` | `/compact` 이후 |
3338| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달하여 자동 압축된 이후 |3344| `auto` | 대화가 [자동 압축 윈도우](/docs/ko/model-config#set-the-auto-compact-window)에 도달하여 자동 압축된 이후 |
3341 PostCompact 입력3347 PostCompact 입력
3342</h4>3348</h4>
3343 3349
3344[공통 입력 필드](#common-input-fields) 외에도 PostCompact 훅은 `trigger`와 `compact_summary`를 받습니다. `compact_summary` 필드에는 압축 작업으로 생성된 대화 요약이 담깁니다.3350[공통 입력 필드](#common-input-fields)에 더해 PostCompact 훅은 `trigger`와 `compact_summary`를 받습니다. `compact_summary` 필드에는 압축 작업으로 생성된 대화 요약이 담깁니다.
3345 3351
3346```json theme={null}3352```json theme={null}
3347{3353{
3360 PreModelSwitch3366 PreModelSwitch
3361</h3>3367</h3>
3362 3368
3363사용자 또는 클라이언트가 요청한 모델 전환을 Claude Code가 적용하기 전에 실행됩니다. 전환을 차단하거나, 확인을 요구하거나, 전환이 일어나기 전에 전환 비용을 보여 주는 데 사용합니다.3369사용자나 클라이언트가 요청한 모델 전환을 Claude Code가 적용하기 전에 실행됩니다. 전환을 차단하거나, 확인을 요구하거나, 전환이 일어나기 전에 전환 비용을 표시하는 데 사용하십시오.
3364 3370
3365PreModelSwitch에는 Claude Code v2.1.251 이상이 필요합니다. Claude Code는 다음 요청에 대해 이 훅을 실행합니다.3371PreModelSwitch를 사용하려면 Claude Code v2.1.251 이상이 필요합니다. Claude Code는 다음 요청에 대해 이 훅을 실행합니다.
3366 3372
3367* `/model <name>` 및 `/model` 선택기3373* `/model <name>` 및 `/model` 선택기
3368* `Option+P` 또는 `Alt+P` 모델 선택기3374* `Option+P` 또는 `Alt+P` 모델 선택기
3369* `/config`의 Model 설정3375* `/config`의 Model 설정
3370* 세션의 모델을 변경하는 [빠른 모드](/docs/ko/fast-mode) 켜기3376* [빠른 모드](/docs/ko/fast-mode)를 켜서 세션의 모델이 변경되는 경우
3371* [Agent SDK](/docs/ko/agent-sdk/typescript#query-object) 호스트 또는 [Remote Control](/docs/ko/remote-control)의 `set_model` 요청, 또는 `apply_flag_settings` 요청에 포함된 모델 변경3377* [Agent SDK](/docs/ko/agent-sdk/typescript#query-object) 호스트 또는 [Remote Control](/docs/ko/remote-control)에서 보낸 `set_model` 요청이나 `apply_flag_settings` 요청 내의 모델 변경
3372 3378
3373Claude Code는 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)이나 세션 재개 시 모델 복원처럼 자체적으로 수행하는 전환에 대해서는 PreModelSwitch 훅을 실행하지 않습니다. 이러한 변경은 [PostModelSwitch](#postmodelswitch)에만 전달됩니다.3379[자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)이나 세션을 재개할 때의 모델 복원처럼 Claude Code가 자체적으로 수행하는 전환에 대해서는 PreModelSwitch 훅을 실행하지 않습니다. 이러한 변경은 [PostModelSwitch](#postmodelswitch)에만 전달됩니다.
3374 3380
3375Claude Code는 `[1m]` 접미사를 무시하고, 세션이 전환하려는 모델의 정식 이름과 matcher를 비교합니다. `opus`와 같은 별칭, 날짜가 포함된 모델 ID, Amazon Bedrock 모델 ID와 같은 제공업체별 ID는 모두 해석 결과인 하나의 정식 이름과 일치하므로, `claude-opus-5`는 Opus 5의 모든 표기를 포괄합니다.3381Claude Code는 `[1m]` 접미사를 무시하고 세션이 전환하려는 모델의 정식 이름과 matcher를 비교합니다. `opus` 같은 별칭, 날짜가 포함된 모델 ID, Amazon Bedrock 모델 ID 같은 공급자별 ID는 모두 해석되는 하나의 정식 이름과 일치하므로, `claude-opus-5`는 Opus 5의 모든 표기를 포괄합니다.
3376 3382
3377[LLM 게이트웨이](/docs/ko/llm-gateway)만 아는 사용자 지정 모델 ID처럼 Claude Code가 대상의 정식 이름을 확인할 수 없는 경우에는 matcher와 관계없이 모든 PreModelSwitch 훅을 실행합니다. 따라서 차단하는 훅은 matcher에만 의존하지 말고 입력의 `to_model`을 확인해야 합니다.3383대상의 정식 이름을 확인할 수 없는 경우(예: [LLM 게이트웨이](/docs/ko/llm-gateway)만 알고 있는 사용자 지정 모델 ID) Claude Code는 matcher와 관계없이 모든 PreModelSwitch 훅을 실행합니다. 따라서 차단하는 훅은 matcher에만 의존하지 말고 입력의 `to_model`을 확인해야 합니다.
3378 3384
3379matcher는 정확한 이름, `claude-opus-4-6|claude-opus-5`와 같은 `|`로 구분된 목록, 또는 `.*opus.*`와 같은 정규식으로 작성합니다. 다음 예시는 정확한 이름 matcher를 사용하면서 훅 입력의 `to_model`도 확인하므로, 코드 2로 종료하여 Opus 4.6으로의 전환을 거부하고 다른 대상은 허용합니다.3385matcher는 정확한 이름, `claude-opus-4-6|claude-opus-5`처럼 `|`로 구분된 목록, 또는 `.*opus.*` 같은 정규식으로 작성합니다. 다음 예시는 정확한 이름 matcher를 사용하면서 훅 입력의 `to_model`도 확인하여, Opus 4.6으로의 전환은 코드 2로 종료하여 거부하고 다른 대상은 허용합니다.
3380 3386
3381<Tabs>3387<Tabs>
3382 <Tab title="macOS/Linux">3388 <Tab title="macOS/Linux">
3383 명령이 `jq`로 `to_model`을 확인합니다.3389 명령은 `jq`로 `to_model`을 확인합니다.
3384 3390
3385 ```json theme={null}3391 ```json theme={null}
3386 {3392 {
3442 </Tab>3448 </Tab>
3443</Tabs>3449</Tabs>
3444 3450
3445훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 `/model claude-opus-4-6`을 실행합니다. Claude Code는 현재 모델을 유지하고, PreModelSwitch 훅이 전환을 차단했다고 보고하며, 작성한 메시지를 이유로 표시합니다.3451훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 `/model claude-opus-4-6`을 실행하십시오. Claude Code는 현재 모델을 유지하고, PreModelSwitch 훅이 전환을 차단했다고 사용자의 메시지를 사유로 함께 보고합니다.
3446 3452
3447<h4 id="premodelswitch-input">3453<h4 id="premodelswitch-input">
3448 PreModelSwitch 입력3454 PreModelSwitch 입력
3449</h4>3455</h4>
3450 3456
3451[공통 입력 필드](#common-input-fields) 외에도 PreModelSwitch 훅은 다음 표의 필드를 받습니다. 마지막 다섯 개 필드는 대화를 새 모델로 다시 전송하는 비용을 설명하므로, 훅은 전환이 일어나기 전에 해당 수치를 보여 줄 수 있습니다.3457[공통 입력 필드](#common-input-fields)에 더해 PreModelSwitch 훅은 다음 표의 필드를 받습니다. 마지막 다섯 개 필드는 대화를 새 모델로 다시 전송하는 비용을 나타내므로, 훅은 전환이 일어나기 전에 해당 수치를 표시할 수 있습니다.
3452 3458
3453| 필드 | 유형 | 설명 |3459| 필드 | 타입 | 설명 |
3454| :- | :- | :- |3460| :- | :- | :- |
3455| `from_model` | string | 전환 전 모델 ID |3461| `from_model` | string | 전환 전 모델 ID |
3456| `to_model` | string | 전환 후 모델 ID. matcher는 이 모델의 정식 이름과 비교됩니다 |3462| `to_model` | string | 전환 후 모델 ID. matcher는 이 모델의 정식 이름과 비교됩니다 |
3457| `requested_model` | string 또는 `null` | 요청에 지정된 모델: `opus`와 같은 별칭, 전체 모델 ID, 또는 기본 모델을 요청한 경우 `null` |3463| `requested_model` | string 또는 `null` | 요청에서 지정한 모델: `opus` 같은 별칭, 전체 모델 ID, 또는 기본 모델을 요청한 경우 `null` |
3458| `source` | string | 요청의 출처: `/model <name>`, `/config`의 Model 설정 또는 빠른 모드 켜기의 경우 `"command"`, 모델 선택기의 경우 `"picker"`, Agent SDK 호스트 또는 Remote Control의 `set_model` 요청이나 `apply_flag_settings` 요청의 모델 변경의 경우 `"sdk"` |3464| `source` | string | 요청의 출처: `/model <name>`, `/config`의 Model 설정, 빠른 모드 켜기의 경우 `"command"`, 모델 선택기의 경우 `"picker"`, Agent SDK 호스트 또는 Remote Control에서 보낸 `set_model` 요청이나 `apply_flag_settings` 요청 내 모델 변경의 경우 `"sdk"` |
3459| `context_tokens` | number | 다음 요청이 프롬프트로 다시 전송하는 토큰: 메인 대화의 마지막 응답에 대한 입력, 캐시 읽기, 캐시 생성 및 출력 토큰의 합계. 첫 번째 응답 이전에는 `0` |3465| `context_tokens` | number | 다음 요청이 프롬프트로 다시 전송하는 토큰: 메인 대화의 마지막 응답에 대한 입력, 캐시 읽기, 캐시 생성, 출력 토큰의 합계. 첫 번째 응답 전에는 `0` |
3460| `prompt_cache_warm` | boolean | 현재 모델의 프롬프트 캐시가 아직 웜 상태일 가능성이 높은지 여부. 웜 상태라면 전환 시 캐시를 잃게 됩니다 |3466| `prompt_cache_warm` | boolean | 현재 모델의 프롬프트 캐시가 아직 활성 상태일 가능성이 높은지 여부. 즉 전환 시 해당 캐시를 잃게 됨을 의미합니다 |
3461| `cache_ttl` | string | Claude Code가 이 세션에 요청하는 [프롬프트 캐시 수명](/docs/ko/prompt-caching#cache-lifetime): `"5m"` 또는 `"1h"` |3467| `cache_ttl` | string | Claude Code가 이 세션에 요청하는 [프롬프트 캐시 수명](/docs/ko/prompt-caching#cache-lifetime): `"5m"` 또는 `"1h"` |
3462| `estimated_cache_write_usd` | number | `to_model`에서 `cache_ttl` 요율로 `context_tokens`를 프롬프트 캐시에 쓰는 예상 비용(미화 달러). 다음 응답은 제외됩니다. 서버가 전체 컨텍스트를 다시 캐싱할 필요가 없을 수도 있으므로 추정치로 취급하십시오 |3468| `estimated_cache_write_usd` | number | `to_model`에서 `cache_ttl` 요율로 `context_tokens`를 프롬프트 캐시에 쓰는 예상 비용(미국 달러)이며, 다음 응답은 제외됩니다. 서버가 전체 컨텍스트를 다시 캐시할 필요가 없을 수 있으므로 추정치로 취급하십시오 |
3463| `pricing` | string | Claude Code가 `estimated_cache_write_usd`의 가격을 산정한 방식: 조직이 자체 요율을 구성한 경우 해당 요율을 적용한 `"configured"`, 정가를 적용한 `"catalog"`, `to_model`의 가격을 알 수 없어 Claude Code가 기본 요율을 가정한 경우 `"default"` |3469| `pricing` | string | Claude Code가 `estimated_cache_write_usd`를 산정한 방식: 조직이 자체 요율을 구성한 경우 해당 요율로 산정한 `"configured"`, 정가로 산정한 `"catalog"`, 또는 `to_model`의 가격을 알 수 없어 Claude Code가 기본 요율을 가정한 경우 `"default"` |
3464 3470
3465다음 예시는 Sonnet 5를 실행 중인 세션에서 `/model opus`를 실행할 때의 입력을 보여 줍니다.3471다음 예시는 Sonnet 5를 실행 중인 세션에서 `/model opus`를 실행했을 때의 입력을 보여 줍니다.
3466 3472
3467```json theme={null}3473```json theme={null}
3468{3474{
3486 PreModelSwitch 결정 제어3492 PreModelSwitch 결정 제어
3487</h4>3493</h4>
3488 3494
3489`PreModelSwitch` 훅은 전환을 취소하거나, 사용자에게 확인을 요청하거나, 전환을 진행하도록 할 수 있습니다. 종료 코드 2 또는 최상위 수준의 `decision: "block"`은 전환을 취소합니다.3495`PreModelSwitch` 훅은 전환을 취소하거나, 사용자에게 확인을 요청하거나, 전환을 진행하도록 할 수 있습니다. 종료 코드 2 또는 최상위 `decision: "block"`은 전환을 취소합니다.
3490 3496
3491보다 세밀하게 제어하려면 [PreToolUse](#pretooluse-decision-control)와 마찬가지로 `hookSpecificOutput` 객체에 `permissionDecision`과 `permissionDecisionReason`을 반환합니다. `PreModelSwitch`는 `"allow"`, `"deny"`, `"ask"`를 허용합니다. `"defer"`, `updatedInput`, `additionalContext`는 허용하지 않습니다. 아래 표에서 두 필드를 설명합니다.3497더 세밀하게 제어하려면 [PreToolUse](#pretooluse-decision-control)와 마찬가지로 `hookSpecificOutput` 객체에 `permissionDecision`과 `permissionDecisionReason`을 반환하십시오. `PreModelSwitch`는 `"allow"`, `"deny"`, `"ask"`를 허용합니다. `"defer"`, `updatedInput`, `additionalContext`는 허용하지 않습니다. 아래 표는 두 필드를 설명합니다.
3492 3498
3493| 필드 | 설명 |3499| 필드 | 설명 |
3494| :- | :- |3500| :- | :- |
3495| `permissionDecision` | `"allow"`는 전환을 진행하며 [프롬프트 캐시가 웜 상태일 때 Claude Code가 표시하는 확인](/docs/ko/prompt-caching#switching-models)을 건너뜁니다. `"deny"`는 전환을 취소합니다. `"ask"`는 사용자에게 확인을 요청합니다 |3501| `permissionDecision` | `"allow"`는 전환을 진행하며 [프롬프트 캐시가 활성 상태일 때 Claude Code가 표시하는 확인](/docs/ko/prompt-caching#switching-models)을 건너뜁니다. `"deny"`는 전환을 취소합니다. `"ask"`는 사용자에게 확인을 요청합니다 |
3496| `permissionDecisionReason` | `"deny"`의 경우 전환이 차단된 이유로 사용자에게 표시되거나, `set_model` 요청에 대한 오류로 반환됩니다. `"ask"`의 경우 확인 프롬프트에 표시됩니다. `"allow"`의 경우 무시됩니다 |3502| `permissionDecisionReason` | `"deny"`의 경우 전환이 차단된 사유로 사용자에게 표시되거나, `set_model` 요청에 대한 오류로 반환됩니다. `"ask"`의 경우 확인 프롬프트에 표시됩니다. `"allow"`의 경우 무시됩니다 |
3497 3503
3498대화형 세션의 `/model`만 `"ask"` 프롬프트를 표시할 수 있습니다. `-p` 플래그를 사용하는 비대화형 모드, `/config`, `set_model` 요청을 포함한 다른 모든 사용 환경에서는 Claude Code가 `"ask"`를 거부로 처리합니다.3504`"ask"` 프롬프트는 대화형 세션의 `/model`에서만 표시될 수 있습니다. `-p` 플래그를 사용한 비대화형 모드, `/config`, `set_model` 요청을 포함한 다른 모든 사용 환경에서 Claude Code는 `"ask"`를 거부로 취급합니다.
3499 3505
3500다음 예시는 사용자에게 확인을 요청하며 `context_tokens`의 토큰 수를 인용합니다.3506다음 예시는 사용자에게 확인을 요청하며 `context_tokens`의 토큰 수를 인용합니다.
3501 3507
3513 3519
3514Claude Code는 결정과 관계없이 훅이 반환한 `systemMessage`를 사용자에게 표시하므로, 비용 보고 훅은 `{"systemMessage": "..."}`를 반환하고 0으로 종료할 수 있습니다.3520Claude Code는 결정과 관계없이 훅이 반환한 `systemMessage`를 사용자에게 표시하므로, 비용 보고 훅은 `{"systemMessage": "..."}`를 반환하고 0으로 종료할 수 있습니다.
3515 3521
3516타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 반면 [PreToolUse](#timeouts)에서는 시간 초과된 명령 훅이 도구 호출을 계속 진행하도록 합니다. 이 이벤트의 기본 타임아웃은 30초입니다. `PreModelSwitch`는 `command`, `http`, `mcp_tool` 훅만 실행하므로 `prompt` 및 `agent` 기본값은 적용되지 않습니다.3522타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 반면 [PreToolUse](#timeouts)에서는 시간 초과된 명령 훅이 도구 호출을 계속 진행시킵니다. 이 이벤트의 기본 타임아웃은 30초입니다. `PreModelSwitch`는 `command`, `http`, `mcp_tool` 훅만 실행하므로 `prompt` 및 `agent` 기본값은 적용되지 않습니다.
3517 3523
35180 또는 2 이외의 코드로 종료하고 JSON 결정을 출력하지 않는 훅은 차단하지 않습니다. [기타 종료 코드](#other-exit-codes)에 설명된 대로 Claude Code는 해당 stderr를 표시하고 전환을 적용합니다.35240 또는 2가 아닌 코드로 종료하고 JSON 결정을 출력하지 않는 훅은 차단하지 않습니다. [기타 종료 코드](#other-exit-codes)에 설명된 대로 Claude Code는 해당 훅의 stderr를 표시하고 전환을 적용합니다.
3519 3525
3520<h3 id="postmodelswitch">3526<h3 id="postmodelswitch">
3521 PostModelSwitch3527 PostModelSwitch
3522</h3>3528</h3>
3523 3529
3524세션의 모델이 변경된 후 실행됩니다. 모든 CLAUDE.md를 편집하지 않고도 Claude에게 모델별 지침을 제공하는 데 사용합니다. 예를 들어 특정 모델에 적용되는 조직 전체 지침을 제공할 수 있습니다.3530세션의 모델이 변경된 후 실행됩니다. 모든 CLAUDE.md를 편집하지 않고도 Claude에게 모델별 지침을 제공하는 데 사용하십시오. 예를 들어 특정 모델에 적용되는 조직 전체 지침을 제공할 수 있습니다.
3525 3531
3526PostModelSwitch에는 Claude Code v2.1.251 이상이 필요합니다. 모델이 이미 변경된 후이므로 차단할 수 없습니다. Claude Code는 다음 변경 후에 PostModelSwitch 훅을 실행합니다.3532PostModelSwitch를 사용하려면 Claude Code v2.1.251 이상이 필요합니다. 모델이 이미 변경된 상태이므로 차단할 수 없습니다. Claude Code는 다음 변경 이후 PostModelSwitch 훅을 실행합니다.
3527 3533
3528* 사용자 또는 클라이언트가 요청한 전환3534* 사용자나 클라이언트가 요청한 전환
3529* 세션의 모델을 변경하는 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)3535* 세션의 모델을 변경하는 [자동 모델 폴백](/docs/ko/model-config#automatic-model-fallback)
3530* [`opusplan`](/docs/ko/model-config#opusplan-model-setting)과 같은 설정에서 플랜 모드에 진입하거나 플랜 모드를 벗어나는 경우3536* [`opusplan`](/docs/ko/model-config#opusplan-model-setting) 같은 설정이 플랜 모드에 진입하거나 플랜 모드를 벗어나는 경우
3531* 세션 재개 시 Claude Code가 모델을 복원하는 경우3537* 세션을 재개할 때 Claude Code가 모델을 복원하는 경우
3532 3538
3533[폴백 모델 체인](/docs/ko/model-config#fallback-model-chains)의 모델이 턴을 처리하는 경우에는 Claude Code가 PostModelSwitch 훅을 실행하지 않습니다. 해당 대체는 한 턴 동안만 지속되며 세션의 모델을 변경하지 않기 때문입니다.3539[대체 모델 체인](/docs/ko/model-config#fallback-model-chains)의 모델이 턴을 처리하는 경우에는 PostModelSwitch 훅을 실행하지 않습니다. 이러한 대체는 한 턴 동안만 유지되며 세션의 모델은 변경되지 않기 때문입니다.
3534 3540
3535matcher는 [PreModelSwitch](#premodelswitch)와 동일한 규칙을 따릅니다. Claude Code는 세션이 전환된 모델의 정식 이름과 matcher를 비교합니다.3541matcher는 [PreModelSwitch](#premodelswitch)와 동일한 규칙을 따릅니다. Claude Code는 세션이 전환된 모델의 정식 이름과 matcher를 비교합니다.
3536 3542
3554}3560}
3555```3561```
3556 3562
3557훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 Opus 모델로 전환한 다음(예: Sonnet 세션에서 `/model opus` 실행), 현재 모델에 대해 어떤 지침을 가지고 있는지 Claude에게 물어보십시오.3563훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 Opus 모델로 전환한 다음(예: Sonnet 세션에서 `/model opus` 실행), Claude에게 현재 모델에 대해 어떤 지침을 받았는지 물어보십시오.
3558 3564
3559<h4 id="postmodelswitch-input">3565<h4 id="postmodelswitch-input">
3560 PostModelSwitch 입력3566 PostModelSwitch 입력
3561</h4>3567</h4>
3562 3568
3563PostModelSwitch 훅은 [PreModelSwitch](#premodelswitch-input)와 동일한 필드를 받으며, `hook_event_name`은 `"PostModelSwitch"`로 설정되고 `source` 값이 두 가지 추가됩니다. 자동 폴백 또는 Claude Code가 자체적으로 수행한 기타 변경의 경우 `"auto"`, 세션 재개 시 복원된 모델의 경우 `"resume"`입니다.3569PostModelSwitch 훅은 [PreModelSwitch](#premodelswitch-input)와 동일한 필드를 받으며, `hook_event_name`은 `"PostModelSwitch"`로 설정되고 `source` 값이 두 가지 추가됩니다. 자동 폴백 또는 Claude Code가 자체적으로 수행한 기타 변경의 경우 `"auto"`, 세션을 재개할 때 복원된 모델의 경우 `"resume"`입니다.
3564 3570
3565`source`가 `"auto"`이면 `requested_model`은 `null`입니다. `source`가 `"resume"`이면 Claude Code가 복원한 저장된 모델 설정입니다.3571`source`가 `"auto"`이면 `requested_model`은 `null`입니다. `source`가 `"resume"`이면 Claude Code가 복원한 저장된 모델 설정입니다.
3566 3572
3568 PostModelSwitch 결정 제어3574 PostModelSwitch 결정 제어
3569</h4>3575</h4>
3570 3576
3571Claude Code는 종료 코드 0일 때 훅의 [일반 텍스트 stdout](#exit-code-0) 또는 JSON 출력의 `additionalContext`를 가져와, 전환 후 다음 요청과 함께 Claude에게 전달합니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output) 외에도 다음을 반환할 수 있습니다.3577Claude Code는 종료 코드 0일 때 훅의 [일반 텍스트 stdout](#exit-code-0) 또는 JSON 출력의 `additionalContext`를 가져와 전환 이후의 다음 요청과 함께 Claude에게 전달합니다. 모든 훅에서 사용할 수 있는 [JSON 출력 필드](#json-output)에 더해 다음을 반환할 수 있습니다.
3572 3578
3573| 필드 | 설명 |3579| 필드 | 설명 |
3574| :- | :- |3580| :- | :- |
3575| `additionalContext` | 다음 요청과 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |3581| `additionalContext` | 다음 요청과 함께 Claude의 컨텍스트에 추가되는 문자열. [Claude에 컨텍스트 추가](#add-context-for-claude)를 참조하십시오 |
3576 3582
3577다음 프롬프트를 보낸 후 5초 이내에 훅이 완료되지 않으면 Claude Code는 출력 없이 해당 요청을 보내고 대신 그다음 요청에 출력을 첨부합니다. 다음 요청 전에 모델이 여러 번 변경되면 Claude Code는 마지막 전환의 대상 모델에 대한 출력만 전달합니다.3583다음 프롬프트를 보낸 후 5초 이내에 훅이 완료되지 않으면 Claude Code는 출력 없이 해당 요청을 보내고, 대신 그다음 요청에 출력을 첨부합니다. 다음 요청 전에 모델이 여러 번 변경되면 Claude Code는 마지막 전환의 대상 모델에 대한 출력만 전달합니다.
3578 3584
3579<h3 id="sessionend">3585<h3 id="sessionend">
3580 SessionEnd3586 SessionEnd
3581</h3>3587</h3>
3582 3588
3583Claude Code 세션이 종료될 때 실행됩니다. 정리 작업, 세션3589Claude Code 세션이 종료될 때 실행됩니다. 정리 작업, 세션 통계 로깅,
3584통계 로깅 또는 세션 상태 저장에 유용합니다. 종료 이유로 필터링하는 matcher를 지원합니다.3590세션 상태 저장에 유용합니다. 종료 사유로 필터링하는 matcher를 지원합니다.
3585 3591
3586훅 입력의 `reason` 필드는 세션이 종료된 이유를 나타냅니다.3592훅 입력의 `reason` 필드는 세션이 종료된 이유를 나타냅니다.
3587 3593
3588| 이유 | 설명 |3594| 사유 | 설명 |
3589| :- | :- |3595| :- | :- |
3590| `clear` | `/clear` 명령으로 세션이 지워짐 |3596| `clear` | `/clear` 명령으로 세션이 지워짐 |
3591| `resume` | 대화형 `/resume`을 통해 세션이 전환됨 |3597| `resume` | 대화형 `/resume`으로 세션이 전환됨 |
3592| `logout` | 사용자가 로그아웃함 |3598| `logout` | 사용자가 로그아웃함 |
3593| `prompt_input_exit` | 프롬프트 입력이 표시된 상태에서 사용자가 종료함 |3599| `prompt_input_exit` | 프롬프트 입력이 표시된 상태에서 사용자가 종료함 |
3594| `other` | 기타 종료 이유 |3600| `other` | 기타 종료 사유 |
3595| `bypass_permissions_disabled` | v2.1.234에서 제거되었으며 Claude Code는 이 값을 보내지 않습니다. `SessionEnd` matcher에서 제거하십시오 |3601| `bypass_permissions_disabled` | v2.1.234에서 제거되었으며 Claude Code는 이 값을 보내지 않습니다. `SessionEnd` matcher에서 제거하십시오 |
3596 3602
3597<h4 id="sessionend-input">3603<h4 id="sessionend-input">
3598 SessionEnd 입력3604 SessionEnd 입력
3599</h4>3605</h4>
3600 3606
3601[공통 입력 필드](#common-input-fields) 외에도 SessionEnd 훅은 세션이 종료된 이유를 나타내는 `reason` 필드를 받습니다. 모든 값은 위의 [이유 표](#sessionend)를 참조하십시오.3607[공통 입력 필드](#common-input-fields)에 더해 SessionEnd 훅은 세션이 종료된 이유를 나타내는 `reason` 필드를 받습니다. 모든 값은 위의 [사유 표](#sessionend)를 참조하십시오.
3602 3608
3603```json theme={null}3609```json theme={null}
3604{3610{
3610}3616}
3611```3617```
3612 3618
3613SessionEnd 훅에는 결정 제어 기능이 없습니다. 세션 종료를 차단할 수는 없지만 정리 작업을 수행할 수 있습니다. Claude Code는 `systemMessage` 등 해당 훅의 [JSON 출력 필드](#json-output)를 무시합니다.3619SessionEnd 훅에는 결정 제어 기능이 없습니다. 세션 종료를 차단할 수는 없지만 정리 작업을 수행할 수 있습니다. Claude Code는 `systemMessage` 등 이 훅의 [JSON 출력 필드](#json-output)를 폐기합니다.
3614 3620
3615SessionEnd 훅의 기본 타임아웃은 1.5초입니다. 이 타임아웃은 종료할 때, `/clear`를 실행할 때, 또는 대화형 `/resume`으로 세션을 전환할 때 적용됩니다. 훅에 더 많은 시간을 주는 방법은 두 가지입니다.3621SessionEnd 훅의 기본 타임아웃은 1.5초입니다. 이는 종료할 때, `/clear`를 실행할 때, 대화형 `/resume`으로 세션을 전환할 때 적용됩니다. 훅에 더 많은 시간을 주는 방법은 두 가지입니다.
3616 3622
3617* **훅별 `timeout`**: 해당 훅의 구성에서 `timeout`을 설정합니다. 전체 허용 시간은 설정 파일에 있는 가장 높은 훅별 `timeout`에 맞춰 최대 60초까지 자동으로 늘어납니다. 이 방식으로 허용 시간을 늘려도 자체 `timeout`이 없는 훅은 여전히 기본값을 유지합니다. 플러그인이 제공하는 훅에 설정된 타임아웃은 허용 시간을 늘리지 않습니다.3623* **훅별 `timeout`**: 해당 훅의 구성에 `timeout`을 설정합니다. 전체 예산은 설정 파일에 있는 가장 높은 훅별 `timeout`에 맞춰 최대 60초까지 자동으로 늘어납니다. 이 방식으로 예산을 늘려도 자체 `timeout`이 없는 훅은 여전히 기본값을 유지합니다. 플러그인이 제공하는 훅에 설정된 타임아웃은 예산을 늘리지 않습니다.
3618* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: 이 환경 변수를 밀리초 단위로 설정하여 허용 시간을 명시적으로 재정의합니다. 설정한 값은 자체 `timeout`이 없는 각 훅의 타임아웃으로도 사용됩니다.3624* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: 이 환경 변수를 밀리초 단위로 설정하여 예산을 명시적으로 재정의합니다. 설정한 값은 자체 `timeout`이 없는 각 훅의 타임아웃으로도 사용됩니다.
3619 3625
3620다음 예시는 허용 시간을 5초로 설정합니다.3626다음 예시는 예산을 5초로 설정합니다.
3621 3627
3622```bash theme={null}3628```bash theme={null}
3623CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3629CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3624```3630```
3625 3631
3626v2.1.268 이전에는 `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`가 전체 허용 시간만 늘렸으며, 자체 `timeout`이 없는 훅은 여전히 1.5초 후에 취소되었습니다.3632v2.1.268 이전에는 `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`가 전체 예산만 늘렸으며, 자체 `timeout`이 없는 훅은 여전히 1.5초 후에 취소되었습니다.
3627 3633
3628<h3 id="elicitation">3634<h3 id="elicitation">
3629 Elicitation3635 Elicitation
3630</h3>3636</h3>
3631 3637
3632MCP 서버가 작업 도중 사용자 입력을 요청할 때 실행됩니다. 기본적으로 Claude Code는 사용자가 응답할 수 있도록 대화형 대화 상자를 표시합니다. 훅은 이 요청을 가로채 프로그래밍 방식으로 응답하여 대화 상자를 완전히 건너뛸 수 있습니다.3638MCP 서버가 작업 도중 사용자 입력을 요청할 때 실행됩니다. 기본적으로 Claude Code는 사용자가 응답할 수 있는 대화형 대화 상자를 표시합니다. 훅은 이 요청을 가로채 프로그래밍 방식으로 응답하여 대화 상자를 완전히 건너뛸 수 있습니다.
3633 3639
3634matcher 필드는 MCP 서버 이름과 비교됩니다.3640matcher 필드는 MCP 서버 이름과 비교됩니다.
3635 3641
3637 Elicitation 입력3643 Elicitation 입력
3638</h4>3644</h4>
3639 3645
3640[공통 입력 필드](#common-input-fields) 외에도 Elicitation 훅은 `mcp_server_name`, `message` 및 선택적 필드인 `mode`, `url`, `elicitation_id`, `requested_schema`를 받습니다.3646[공통 입력 필드](#common-input-fields)에 더해 Elicitation 훅은 `mcp_server_name`, `message` 필드와 선택적 필드인 `mode`, `url`, `elicitation_id`, `requested_schema`를 받습니다.
3641 3647
3642가장 일반적인 경우인 폼 모드 elicitation의 예시입니다.3648가장 일반적인 경우인 폼 모드 elicitation의 예:
3643 3649
3644```json theme={null}3650```json theme={null}
3645{3651{
3659}3665}
3660```3666```
3661 3667
3662브라우저 기반 인증에 사용되는 URL 모드 elicitation의 예시입니다.3668브라우저 기반 인증에 사용되는 URL 모드 elicitation의 예:
3663 3669
3664```json theme={null}3670```json theme={null}
3665{3671{
3678 Elicitation 출력3684 Elicitation 출력
3679</h4>3685</h4>
3680 3686
3681대화 상자를 표시하지 않고 프로그래밍 방식으로 응답하려면 `hookSpecificOutput`이 포함된 JSON 객체를 반환합니다.3687대화 상자를 표시하지 않고 프로그래밍 방식으로 응답하려면 `hookSpecificOutput`이 포함된 JSON 객체를 반환하십시오.
3682 3688
3683```json theme={null}3689```json theme={null}
3684{3690{
3695| 필드 | 값 | 설명 |3701| 필드 | 값 | 설명 |
3696| :- | :- | :- |3702| :- | :- | :- |
3697| `action` | `accept`, `decline`, `cancel` | 요청을 수락, 거절 또는 취소할지 여부 |3703| `action` | `accept`, `decline`, `cancel` | 요청을 수락, 거절 또는 취소할지 여부 |
3698| `content` | object | 제출할 폼 필드 값. `action`이 `accept`인 경우에만 사용됩니다 |3704| `content` | object | 제출할 폼 필드 값. `action`이 `accept`일 때만 사용됩니다 |
3699 3705
3700종료 코드 2는 elicitation을 거부합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.3706종료 코드 2는 elicitation을 거부합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.
3701 3707
3702Claude Code는 Elicitation 훅의 JSON 출력에서 `hookSpecificOutput`에 따라 동작하며 `systemMessage`와 `continue`는 무시합니다.3708Claude Code는 Elicitation 훅의 JSON 출력 중 `hookSpecificOutput`에 따라 동작하며 `systemMessage`와 `continue`는 폐기합니다.
3703 3709
3704<h3 id="elicitationresult">3710<h3 id="elicitationresult">
3705 ElicitationResult3711 ElicitationResult
3713 ElicitationResult 입력3719 ElicitationResult 입력
3714</h4>3720</h4>
3715 3721
3716[공통 입력 필드](#common-input-fields) 외에도 ElicitationResult 훅은 `mcp_server_name`, `action` 및 선택적 필드인 `mode`, `elicitation_id`, `content`를 받습니다.3722[공통 입력 필드](#common-input-fields)에 더해 ElicitationResult 훅은 `mcp_server_name`, `action` 필드와 선택적 필드인 `mode`, `elicitation_id`, `content`를 받습니다.
3717 3723
3718```json theme={null}3724```json theme={null}
3719{3725{
3733 ElicitationResult 출력3739 ElicitationResult 출력
3734</h4>3740</h4>
3735 3741
3736사용자의 응답을 재정의하려면 `hookSpecificOutput`이 포함된 JSON 객체를 반환합니다.3742사용자의 응답을 재정의하려면 `hookSpecificOutput`이 포함된 JSON 객체를 반환하십시오.
3737 3743
3738```json theme={null}3744```json theme={null}
3739{3745{
3747 3753
3748| 필드 | 값 | 설명 |3754| 필드 | 값 | 설명 |
3749| :- | :- | :- |3755| :- | :- | :- |
3750| `action` | `accept`, `decline`, `cancel` | 사용자의 작업을 재정의합니다 |3756| `action` | `accept`, `decline`, `cancel` | 사용자의 동작을 재정의합니다 |
3751| `content` | object | 폼 필드 값을 재정의합니다. `action`이 `accept`인 경우에만 의미가 있습니다 |3757| `content` | object | 폼 필드 값을 재정의합니다. `action`이 `accept`일 때만 의미가 있습니다 |
3752 3758
3753종료 코드 2는 응답을 차단하여 실제 적용되는 작업을 `decline`으로 변경합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.3759종료 코드 2는 응답을 차단하며, 실제 동작을 `decline`으로 변경합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.
3754 3760
3755Claude Code는 ElicitationResult 훅의 JSON 출력에서 `hookSpecificOutput`에 따라 동작하며 `systemMessage`와 `continue`는 무시합니다.3761Claude Code는 ElicitationResult 훅의 JSON 출력 중 `hookSpecificOutput`에 따라 동작하며 `systemMessage`와 `continue`는 폐기합니다.
3756 3762
3757<h2 id="prompt-based-hooks">3763<h2 id="prompt-based-hooks">
3758 프롬프트 기반 hook3764 프롬프트 기반 hook
