훅(SDK Hooks)

[!tldr] 한줄 요약 Agent SDK Hook은 Python/TypeScript 콜백 함수로 에이전트 라이프사이클 이벤트를 가로채어 도구 차단, 입력 수정, 로깅, 권한 제어 등을 프로그래밍 방식으로 수행한다. CLI Hook의 셸 커맨드 방식과 달리 네이티브 코드로 동작한다.

핵심 내용

CLI Hook vs SDK Hook

Hooks에서 학습한 CLI Hook은 settings.json에 셸 커맨드를 등록하는 방식이었다. SDK Hook은 콜백 함수로 에이전트 동작을 제어한다.

동작 원리

sequenceDiagram
    participant Agent as 에이전트
    participant SDK as SDK
    participant Hook as 콜백 함수

    Agent->>SDK: 이벤트 발생 (예: PreToolUse)
    SDK->>SDK: 등록된 훅 수집
    SDK->>SDK: Matcher 패턴으로 필터링
    SDK->>Hook: input_data, tool_use_id, context 전달
    Hook->>Hook: 검증/로깅/변환 수행
    Hook-->>SDK: 결정 반환 (allow/deny/수정)
    SDK-->>Agent: 결정에 따라 진행/차단

설정 방법

Python:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])
        ]
    }
)

TypeScript:

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Your prompt",
  options: {
    hooks: {
      PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]
    }
  }
})) {
  console.log(message);
}

hooks 객체의 키는 이벤트명, 값은 HookMatcher 배열이다. 각 matcher는 선택적 정규식 패턴과 콜백 함수 배열을 포함한다.

사용 가능한 이벤트

[!warning] Python SDK 제약 SessionStart/SessionEnd는 Python SDK 콜백으로 등록 불가. setting_sources=["project"]로 셸 커맨드 Hook을 로드하는 방식으로 대체해야 한다.

콜백 함수 구조

입력 (3개 인자):

출력:

{} 반환 시 아무 변경 없이 허용한다.

[!important] 우선순위 규칙 여러 훅이 동시에 적용될 때: deny > ask > allow. 하나라도 deny를 반환하면 다른 훅의 allow와 무관하게 차단된다.

비동기 출력

로깅/웹훅 등 사이드 이펙트만 수행하고 에이전트를 기다리게 하지 않으려면:

async def async_hook(input_data, tool_use_id, context):
    asyncio.create_task(send_to_logging_service(input_data))
    return {"async_": True, "asyncTimeout": 30000}  # ms

비동기 출력은 차단/수정/컨텍스트 주입이 불가능하다 (에이전트가 이미 진행했으므로). 사이드 이펙트 전용.

훅 체이닝

훅은 배열 순서대로 실행된다. 각 훅은 단일 책임에 집중:

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(hooks=[rate_limiter]),        # 1. 속도 제한
            HookMatcher(hooks=[authorization_check]),  # 2. 권한 검증
            HookMatcher(hooks=[input_sanitizer]),      # 3. 입력 살균
            HookMatcher(hooks=[audit_logger]),         # 4. 감사 로깅
        ]
    }
)

Matcher 패턴

Matcher는 도구 이름만 필터링한다. 파일 경로 등으로 필터링하려면 콜백 내부에서 tool_input을 검사해야 한다.

예시

.env 파일 보호 (PreToolUse)

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "systemMessage": ".env 파일은 보호 대상입니다.",
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

읽기 전용 도구 자동 승인

async def auto_approve_read_only(input_data, tool_use_id, context):
    read_only_tools = ["Read", "Glob", "Grep"]
    if input_data["tool_name"] in read_only_tools:
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "allow",
                "permissionDecisionReason": "Read-only tool auto-approved",
            }
        }
    return {}

Slack 알림 전송 (Notification)

const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {
  const notification = input as NotificationHookInput;
  try {
    await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: `Agent: ${notification.message}` }),
      signal
    });
  } catch (error) {
    console.error("Failed to send notification:", error);
  }
  return {};
};

참고 자료

• Intercept and control agent behavior with hooks - Claude API Docs
• Hooks reference - Claude Code Docs
• TypeScript SDK reference
• Python SDK reference

관련 노트

• Hooks — CLI 셸 커맨드 방식의 Hook (settings.json 기반)
• 서브에이전트(Subagents) — SubagentStart/Stop 훅으로 추적 가능
• MCP(Model Context Protocol) — MCP 도구는 ^mcp__ 패턴으로 매칭
• Permission 모드(Permission Mode) — permissionDecision으로 권한 제어
• Security와 Sandboxing — 훅을 통한 보안 정책 강제