agent-sdk/hooks.md +13 −13
24 </Step>24 </Step>
25 25
26 <Step title="SDK가 등록된 훅을 수집합니다">26 <Step title="SDK가 등록된 훅을 수집합니다">
2727 SDK는 해당 이벤트 유형에 대해 등록된 훅을 확인합니다. 여기에는 `options.hooks`에 전달하는 콜백 훅과 해당 [`settingSources`](/ko/agent-sdk/typescript#setting-source) 또는 [`setting_sources`](/ko/agent-sdk/python#setting-source) 항목이 활성화된 경우 설정 파일의 셸 명령 훅이 포함되며, 기본 `query()` 옵션에서는 활성화됩니다. SDK는 해당 이벤트 유형에 대해 등록된 훅을 확인합니다. 여기에는 `options.hooks`에 전달하는 콜백 훅과 해당 [`settingSources`](/ko/agent-sdk/typescript#settingSources) 또는 [`setting_sources`](/ko/agent-sdk/python#setting_sources) 항목이 활성화된 경우 설정 파일의 셸 명령 훅이 포함되며, 기본 `query()` 옵션에서는 활성화됩니다.
28 </Step>28 </Step>
29 29
30 <Step title="매처가 실행할 훅을 필터링합니다">30 <Step title="매처가 실행할 훅을 필터링합니다">
40 </Step>40 </Step>
41</Steps>41</Steps>
42 42
4343다음 예제는 이러한 단계를 함께 보여줍니다. `PreToolUse` 훅(단계 1)을 `"Write|Edit"` 매처(단계 3)로 등록하므로 콜백은 파일 쓰기 도구에만 발생합니다. 트리거되면 콜백은 도구의 입력(단계 4)을 받고 파일 경로가 `.env` 파일을 대상으로 하는지 확인한 후 `permissionDecision: "deny"`를 반환하여 작업을 차단합니다(단계 5).다음 예제는 이러한 단계를 함께 보여줍니다. `PreToolUse` 훅(단계 1)을 `"Write|Edit"` 매처(단계 3)로 등록하므로 콜백은 파일 쓰기 도구에만 발생합니다. 트리거되면 콜백은 도구의 입력(단계 4)을 받고 파일 경로가 `.env` 파일을 대상으로 하는지 확인한 후 `permissionDecision: "deny"`를 반환하여 작업을 차단합니다(단계 5):
44 44
45<CodeGroup>45<CodeGroup>
46 ```python Python theme={null}46 ```python Python theme={null}
225 225
226모든 훅 콜백은 세 가지 인수를 받습니다.226모든 훅 콜백은 세 가지 인수를 받습니다.
227 227
228228* **입력 데이터:** 이벤트 세부 정보를 포함하는 입력된 객체입니다. 각 훅 유형은 자체 입력 형태를 가집니다(예: `PreToolUseHookInput`은 `tool_name`과 `tool_input`을 포함하고, `NotificationHookInput`은 `message`를 포함합니다). [TypeScript](/ko/agent-sdk/typescript#hook-input) 및 [Python](/ko/agent-sdk/python#hook-input) SDK 참조에서 전체 타입 정의를 참조하세요.* **입력 데이터:** 이벤트 세부 정보를 포함하는 입력된 객체입니다. 각 훅 유형은 자체 입력 형태를 가집니다(예: `PreToolUseHookInput`은 `tool_name`과 `tool_input`을 포함하고, `NotificationHookInput`은 `message`를 포함합니다). [TypeScript](/ko/agent-sdk/typescript#hookinput) 및 [Python](/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 타입 정의를 참조하세요.
229 * 모든 훅 입력은 `session_id`, `cwd`, `hook_event_name`을 공유합니다.229 * 모든 훅 입력은 `session_id`, `cwd`, `hook_event_name`을 공유합니다.
230 * `agent_id`와 `agent_type`은 훅이 서브에이전트 내에서 발생할 때 채워집니다. TypeScript에서는 기본 훅 입력에 있으며 모든 훅 유형에서 사용 가능합니다. Python에서는 `PreToolUse`, `PostToolUse`, `PostToolUseFailure`에만 있습니다.230 * `agent_id`와 `agent_type`은 훅이 서브에이전트 내에서 발생할 때 채워집니다. TypeScript에서는 기본 훅 입력에 있으며 모든 훅 유형에서 사용 가능합니다. Python에서는 `PreToolUse`, `PostToolUse`, `PostToolUseFailure`에만 있습니다.
231* **도구 사용 ID** (`str | None` / `string | undefined`): 동일한 도구 호출에 대해 `PreToolUse` 및 `PostToolUse` 이벤트를 연결합니다.231* **도구 사용 ID** (`str | None` / `string | undefined`): 동일한 도구 호출에 대해 `PreToolUse` 및 `PostToolUse` 이벤트를 연결합니다.
236콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다.236콜백은 두 가지 필드 범주를 포함하는 객체를 반환합니다.
237 237
238* **최상위 필드**는 대화를 제어합니다. `systemMessage`는 모델에 표시되는 메시지를 대화에 주입하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다.238* **최상위 필드**는 대화를 제어합니다. `systemMessage`는 모델에 표시되는 메시지를 대화에 주입하고, `continue`(Python에서는 `continue_`)는 이 훅 후에 에이전트가 계속 실행되는지 여부를 결정합니다.
239239* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다. `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, 또는 `"ask"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. TypeScript SDK에서 `permissionDecision`은 또한 `"defer"`를 수락하여 쿼리를 종료하고 [나중에 재개](/ko/hooks#defer-a-tool-call-for-later)합니다. 이 값은 Python SDK에서 사용할 수 없습니다. `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가하거나 `updatedToolOutput`을 설정하여 Claude가 보기 전에 도구의 출력을 완전히 바꿀 수 있습니다.* \*\*`hookSpecificOutput`\*\*은 현재 작업을 제어합니다. 내부의 필드는 훅 이벤트 유형에 따라 다릅니다. `PreToolUse` 훅의 경우 `permissionDecision`(`"allow"`, `"deny"`, `"ask"`, 또는 `"defer"`), `permissionDecisionReason`, `updatedInput`을 설정하는 곳입니다. `"defer"`를 반환하면 쿼리가 종료되어 [나중에 재개](/ko/hooks#defer-a-tool-call-for-later)할 수 있습니다. `PostToolUse` 훅의 경우 `additionalContext`를 설정하여 도구 결과에 정보를 추가하거나 `updatedToolOutput`을 설정하여 Claude가 보기 전에 도구의 출력을 완전히 바꿀 수 있습니다.
240 240
241241변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/ko/agent-sdk/typescript#sync-hook-json-output) 및 [Python](/ko/agent-sdk/python#sync-hook-json-output) SDK 참조를 참조하세요.변경 없이 작업을 허용하려면 `{}`를 반환합니다. SDK 콜백 훅은 [Claude Code 셸 명령 훅](/ko/hooks#json-output)과 동일한 JSON 출력 형식을 사용하며, 이는 모든 필드와 이벤트별 옵션을 문서화합니다. SDK 타입 정의는 [TypeScript](/ko/agent-sdk/typescript#synchookjsonoutput) 및 [Python](/ko/agent-sdk/python#synchookjsonoutput) SDK 참조를 참조하세요.
242 242
243<Note>243<Note>
244 여러 훅 또는 권한 규칙이 적용되는 경우 **deny**는 **defer**보다 우선하고, **defer**는 **ask**보다 우선하고, **ask**는 **allow**보다 우선합니다. 훅이 `deny`를 반환하면 다른 훅에 관계없이 작업이 차단됩니다.244 여러 훅 또는 권한 규칙이 적용되는 경우 **deny**는 **defer**보다 우선하고, **defer**는 **ask**보다 우선하고, **ask**는 **allow**보다 우선합니다. 훅이 `deny`를 반환하면 다른 훅에 관계없이 작업이 차단됩니다.
326</CodeGroup>326</CodeGroup>
327 327
328<Note>328<Note>
329329 `updatedInput`을 사용할 때는 `permissionDecision: 'allow'`도 포함해야 합니다. 항상 원본 `tool_input`을 변경하지 않고 새 객체를 반환합니다. `updatedInput`을 사용할 때는 수정된 입력을 자동 승인하기 위해 `permissionDecision: 'allow'`를 포함하거나 사용자에게 표시하기 위해 `permissionDecision: 'ask'`를 포함해야 합니다. `'defer'`를 사용하면 `updatedInput`은 무시됩니다. 항상 원본 `tool_input`을 변경하지 않고 새 객체를 반환합니다.
330</Note>330</Note>
331 331
332### 컨텍스트 추가 및 도구 차단332### 컨텍스트 추가 및 도구 차단
489 489
490### 서브에이전트 활동 추적490### 서브에이전트 활동 추적
491 491
492492`SubagentStop` 훅을 사용하여 서브에이전트가 작업을 완료할 때를 모니터링합니다. [TypeScript](/ko/agent-sdk/typescript#hook-input) 및 [Python](/ko/agent-sdk/python#hook-input) SDK 참조에서 전체 입력 타입을 참조하세요. 이 예제는 서브에이전트가 완료될 때마다 요약을 기록합니다.`SubagentStop` 훅을 사용하여 서브에이전트가 작업을 완료할 때를 모니터링합니다. [TypeScript](/ko/agent-sdk/typescript#hookinput) 및 [Python](/ko/agent-sdk/python#hookinput) SDK 참조에서 전체 입력 타입을 참조하세요. 이 예제는 서브에이전트가 완료될 때마다 요약을 기록합니다.
493 493
494<CodeGroup>494<CodeGroup>
495 ```python Python theme={null}495 ```python Python theme={null}
621 621
622### Slack으로 알림 전달622### Slack으로 알림 전달
623 623
624624`Notification` 훅을 사용하여 에이전트에서 시스템 알림을 받고 외부 서비스로 전달합니다. 알림은 특정 이벤트 유형에 대해 발생합니다. `permission_prompt`(Claude가 권한 필요), `idle_prompt`(Claude가 입력 대기 중), `auth_success`(인증 완료), `elicitation_dialog`(Claude가 사용자에게 프롬프트 중). 각 알림에는 인간이 읽을 수 있는 설명이 있는 `message` 필드와 선택적으로 `title`이 포함됩니다.`Notification` 훅을 사용하여 에이전트에서 시스템 알림을 받고 외부 서비스로 전달합니다. 알림은 특정 이벤트 유형에 대해 발생합니다. `permission_prompt`(Claude가 권한 필요), `idle_prompt`(Claude가 입력 대기 중), `auth_success`(인증 완료), `elicitation_dialog`(Claude가 사용자에게 프롬프트 중), `elicitation_response`(사용자가 유도 질문에 답함), `elicitation_complete`(유도 질문이 종료됨). 각 알림에는 인간이 읽을 수 있는 설명이 있는 `message` 필드와 선택적으로 `title`이 포함됩니다.
625 625
626이 예제는 모든 알림을 Slack 채널로 전달합니다. [Slack 수신 웹훅 URL](https://api.slack.com/messaging/webhooks)이 필요하며, 이는 Slack 작업 공간에 앱을 추가하고 수신 웹훅을 활성화하여 생성합니다.626이 예제는 모든 알림을 Slack 채널로 전달합니다. [Slack 수신 웹훅 URL](https://api.slack.com/messaging/webhooks)이 필요하며, 이는 Slack 작업 공간에 앱을 추가하고 수신 웹훅을 활성화하여 생성합니다.
627 627
727* 매처 패턴이 도구 이름과 정확히 일치하는지 확인합니다.727* 매처 패턴이 도구 이름과 정확히 일치하는지 확인합니다.
728* 훅이 `options.hooks`의 올바른 이벤트 유형 아래에 있는지 확인합니다.728* 훅이 `options.hooks`의 올바른 이벤트 유형 아래에 있는지 확인합니다.
729* `Stop` 및 `SubagentStop` 같은 도구가 아닌 훅의 경우 매처는 다른 필드와 일치합니다([매처 패턴](/ko/hooks#matcher-patterns) 참조).729* `Stop` 및 `SubagentStop` 같은 도구가 아닌 훅의 경우 매처는 다른 필드와 일치합니다([매처 패턴](/ko/hooks#matcher-patterns) 참조).
730730* 에이전트가 [`max_turns`](/ko/agent-sdk/python#claude-agent-options) 제한에 도달하면 훅이 발생하지 않을 수 있습니다. 세션이 훅을 실행하기 전에 종료되기 때문입니다.* 에이전트가 [`max_turns`](/ko/agent-sdk/python#claudeagentoptions) 제한에 도달하면 훅이 발생하지 않을 수 있습니다. 세션이 훅을 실행하기 전에 종료되기 때문입니다.
731 731
732### 매처가 예상대로 필터링하지 않음732### 매처가 예상대로 필터링하지 않음
733 733
734734매처는 **도구 이름**만 일치하며, 파일 경로나 다른 인수는 일치하지 않습니다. 파일 경로로 필터링하려면 훅 내에서 `tool_input.file_path`를 확인합니다.매처는 **도구 이름**만 일치하며, 파일 경로나 다른 인수는 일치하지 않습니다. 파일 경로로 필터링하려면 훅 내에서 `tool_input.file_path`를 확인합니다:
735 735
736```typescript theme={null}736```typescript theme={null}
737const myHook: HookCallback = async (input, toolUseID, { signal }) => {737const myHook: HookCallback = async (input, toolUseID, { signal }) => {
757 757
758### 수정된 입력이 적용되지 않음758### 수정된 입력이 적용되지 않음
759 759
760760* `updatedInput`이 최상위 수준이 아닌 `hookSpecificOutput` 내부에 있는지 확인합니다.* `updatedInput`이 최상위 수준이 아닌 `hookSpecificOutput` 내부에 있는지 확인합니다:
761 761
762 ```typescript theme={null}762 ```typescript theme={null}
763 return {763 return {
769 };769 };
770 ```770 ```
771 771
772772* 입력 수정이 적용되려면 `permissionDecision: 'allow'`도 반환해야 합니다.* 입력 수정이 적용되려면 `permissionDecision: 'allow'` 또는 `'ask'`도 반환해야 합니다.
773 773
774* `hookSpecificOutput`에 `hookEventName`을 포함하여 출력이 어떤 훅 유형에 대한 것인지 식별합니다.774* `hookSpecificOutput`에 `hookEventName`을 포함하여 출력이 어떤 훅 유형에 대한 것인지 식별합니다.
775 775
776### Python에서 세션 훅을 사용할 수 없음776### Python에서 세션 훅을 사용할 수 없음
777 777
778778`SessionStart` 및 `SessionEnd`는 TypeScript에서 SDK 콜백 훅으로 등록할 수 있지만 Python SDK에서는 사용할 수 없습니다(`HookEvent`는 이를 생략합니다). Python에서는 설정 파일(예: `.claude/settings.json`)에 정의된 [셸 명령 훅](/ko/hooks#hook-events)으로만 사용 가능합니다. SDK 애플리케이션에서 셸 명령 훅을 로드하려면 [`setting_sources`](/ko/agent-sdk/python#setting-source) 또는 [`settingSources`](/ko/agent-sdk/typescript#setting-source)를 사용하여 적절한 설정 소스를 포함합니다.`SessionStart` 및 `SessionEnd`는 TypeScript에서 SDK 콜백 훅으로 등록할 수 있지만 Python SDK에서는 사용할 수 없습니다(`HookEvent`는 이를 생략합니다). Python에서는 설정 파일(예: `.claude/settings.json`)에 정의된 [셸 명령 훅](/ko/hooks#hook-events)으로만 사용 가능합니다. SDK 애플리케이션에서 셸 명령 훅을 로드하려면 [`setting_sources`](/ko/agent-sdk/python#settingsource) 또는 [`settingSources`](/ko/agent-sdk/typescript#settingsource)를 사용하여 적절한 설정 소스를 포함합니다:
779 779
780<CodeGroup>780<CodeGroup>
781 ```python Python theme={null}781 ```python Python theme={null}