훅으로 에이전트 동작 가로채기 및 제어

훅을 사용하면 주요 지점에서 에이전트 실행을 가로채 검증, 로깅, 보안 제어 또는 커스텀 로직을 추가할 수 있습니다. 훅을 통해 다음을 수행할 수 있습니다:

파괴적인 셸 명령이나 무단 파일 접근과 같은 위험한 작업을 실행 전에 차단
컴플라이언스, 디버깅 또는 분석을 위해 모든 도구 호출을 로깅 및 감사
데이터 정제, 자격 증명 주입 또는 파일 경로 리디렉션을 위해 입력 및 출력 변환
데이터베이스 쓰기나 API 호출과 같은 민감한 작업에 대해 사람의 승인 요구
상태 관리, 리소스 정리 또는 알림 전송을 위해 세션 수명 주기 추적

훅은 두 부분으로 구성됩니다:

콜백 함수: 훅이 실행될 때 동작하는 로직
훅 구성: SDK에 어떤 이벤트에 훅을 연결할지(예: PreToolUse) 그리고 어떤 도구와 매칭할지 알려줌

다음 예제는 에이전트가 .env 파일을 수정하는 것을 차단합니다. 먼저 파일 경로를 확인하는 콜백을 정의한 다음, Write 또는 Edit 도구 호출 전에 실행되도록 query()에 전달합니다:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

# 도구 호출 세부 정보를 받는 훅 콜백 정의
async def protect_env_files(input_data, tool_use_id, context):
    # 도구의 입력 인수에서 파일 경로 추출
    file_path = input_data['tool_input'].get('file_path', '')
    file_name = file_path.split('/')[-1]

    # .env 파일을 대상으로 하는 경우 작업 차단
    if file_name == '.env':
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Cannot modify .env files'
            }
        }

    # 작업을 허용하려면 빈 객체 반환
    return {}

async def main():
    async for message in query(
        prompt="Update the database configuration",
        options=ClaudeAgentOptions(
            hooks={
                # PreToolUse 이벤트에 훅 등록
                # 매처가 Write 및 Edit 도구 호출만 필터링
                'PreToolUse': [HookMatcher(matcher='Write|Edit', hooks=[protect_env_files])]
            }
        )
    ):
        print(message)

asyncio.run(main())

이것은 PreToolUse 훅입니다. 도구가 실행되기 전에 실행되며 사용자의 로직에 따라 작업을 차단하거나 허용할 수 있습니다. 이 가이드의 나머지 부분에서는 사용 가능한 모든 훅, 구성 옵션 및 일반적인 사용 사례 패턴을 다룹니다.

사용 가능한 훅

SDK는 에이전트 실행의 다양한 단계에 대한 훅을 제공합니다. 일부 훅은 두 SDK 모두에서 사용할 수 있지만, Python SDK가 지원하지 않기 때문에 TypeScript 전용인 훅도 있습니다.

훅 이벤트	Python SDK	TypeScript SDK	트리거 조건	사용 사례 예시
`PreToolUse`	예	예	도구 호출 요청 (차단 또는 수정 가능)	위험한 셸 명령 차단
`PostToolUse`	예	예	도구 실행 결과	모든 파일 변경 사항을 감사 추적에 기록
`PostToolUseFailure`	아니오	예	도구 실행 실패	도구 오류 처리 또는 기록
`UserPromptSubmit`	예	예	사용자 프롬프트 제출	프롬프트에 추가 컨텍스트 주입

일반적인 사용 사례

훅은 다양한 시나리오를 처리할 수 있을 만큼 유연합니다. 다음은 카테고리별로 정리된 가장 일반적인 패턴입니다.

훅 구성

에이전트에 훅을 구성하려면 query() 호출 시 options.hooks 매개변수에 훅을 전달합니다:

async for message in query(
    prompt="Your prompt",
    options=ClaudeAgentOptions(
        hooks={
            'PreToolUse': [HookMatcher(matcher='Bash', hooks=[my_callback])]
        }
    )
):
    print(message)

hooks 옵션은 딕셔너리(Python) 또는 객체(TypeScript)이며:

키는 훅 이벤트 이름입니다 (예: 'PreToolUse', 'PostToolUse', 'Stop')
값은 매처 배열이며, 각각 선택적 필터 패턴과 콜백 함수를 포함합니다

훅 콜백 함수는 이벤트에 대한 입력 데이터를 받고 에이전트가 작업을 허용, 차단 또는 수정할지 알 수 있도록 응답을 반환합니다.

매처

매처를 사용하여 어떤 도구가 콜백을 트리거할지 필터링합니다:

옵션	타입	기본값	설명
`matcher`	`string`	`undefined`	도구 이름과 매칭할 정규식 패턴. 내장 도구에는 `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Task` 등이 포함됩니다. MCP 도구는 `mcp__<server>__<action>` 패턴을 사용합니다.
`hooks`	`HookCallback[]`	-

가능하면 matcher 패턴을 사용하여 특정 도구를 대상으로 지정하세요. 'Bash' 매처는 Bash 명령에 대해서만 실행되지만, 패턴을 생략하면 모든 도구 호출에 대해 콜백이 실행됩니다. 매처는 도구 이름으로만 필터링하며, 파일 경로나 다른 인수로는 필터링하지 않습니다. 파일 경로로 필터링하려면 콜백 내부에서 tool_input.file_path를 확인하세요.

매처는 도구 기반 훅(PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest)에만 적용됩니다. Stop, SessionStart, Notification과 같은 수명 주기 훅의 경우 매처는 무시되며 해당 유형의 모든 이벤트에 대해 훅이 실행됩니다.

도구 이름 확인: 세션이 시작될 때 초기 시스템 메시지의 tools 배열을 확인하거나, 매처 없이 훅을 추가하여 모든 도구 호출을 로깅하세요.

MCP 도구 명명: MCP 도구는 항상 mcp__로 시작하고 서버 이름과 액션이 뒤따릅니다: mcp__<server>__<action>. 예를 들어, playwright라는 이름의 서버를 구성하면 해당 도구는 mcp__playwright__browser_screenshot, mcp__playwright__browser_click 등으로 명명됩니다. 서버 이름은 mcpServers 구성에서 사용하는 키에서 가져옵니다.

이 예제는 PreToolUse 이벤트가 발생할 때 파일 수정 도구에 대해서만 훅을 실행하기 위해 매처를 사용합니다:

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

콜백 함수 입력

모든 훅 콜백은 세 개의 인수를 받습니다:

입력 데이터 (dict / HookInput): 이벤트 세부 정보. 필드는 입력 데이터를 참조하세요
도구 사용 ID (str | None / string | null): PreToolUse와 PostToolUse 이벤트를 연관시킵니다
컨텍스트 (HookContext): TypeScript에서는 취소를 위한 signal 속성(AbortSignal)을 포함합니다. 이를 fetch()와 같은 비동기 작업에 전달하면 훅이 타임아웃될 때 자동으로 취소됩니다. Python에서는 이 인수가 향후 사용을 위해 예약되어 있습니다.

입력 데이터

훅 콜백의 첫 번째 인수에는 이벤트에 대한 정보가 포함됩니다. 필드 이름은 SDK 간에 동일합니다(둘 다 snake_case 사용).

공통 필드 - 모든 훅 유형에 존재:

필드	타입	설명
`hook_event_name`	`string`	훅 유형 (`PreToolUse`, `PostToolUse` 등)
`session_id`	`string`	현재 세션 식별자
`transcript_path`	`string`	대화 트랜스크립트 경로
`cwd`	`string`	현재 작업 디렉토리

훅별 필드는 훅 유형에 따라 다릅니다. ^TS로 표시된 항목은 TypeScript SDK에서만 사용 가능합니다:

필드	타입	설명	훅
`tool_name`	`string`	호출되는 도구의 이름	PreToolUse, PostToolUse, PostToolUseFailure^TS, PermissionRequest^TS
`tool_input`	`object`	도구에 전달되는 인수	PreToolUse, PostToolUse, PostToolUseFailure^TS, PermissionRequest^TS
`tool_response`	`any`	도구 실행에서 반환된 결과	PostToolUse
`error`	`string`	도구 실행 실패의 오류 메시지

아래 코드는 tool_name과 tool_input을 사용하여 각 도구 호출에 대한 세부 정보를 로깅하는 훅 콜백을 정의합니다:

콜백 출력

콜백 함수는 SDK에 진행 방법을 알려주는 객체를 반환합니다. 변경 없이 작업을 허용하려면 빈 객체 {}를 반환합니다. 작업을 차단, 수정 또는 컨텍스트를 추가하려면 결정을 포함하는 hookSpecificOutput 필드가 있는 객체를 반환합니다.

최상위 필드 (hookSpecificOutput 외부):

필드	타입	설명
`continue`	`boolean`	이 훅 이후 에이전트가 계속해야 하는지 여부 (기본값: `true`)
`stopReason`	`string`	`continue`가 `false`일 때 표시되는 메시지
`suppressOutput`	`boolean`	트랜스크립트에서 stdout 숨기기 (기본값: `false`)
`systemMessage`	`string`

hookSpecificOutput 내부 필드:

필드	타입	훅	설명
`hookEventName`	`string`	모두	필수. 현재 이벤트와 매칭하려면 `input.hook_event_name`을 사용
`permissionDecision`	`'allow'` \| `'deny'` \| `'ask'`	PreToolUse	도구 실행 여부를 제어
`permissionDecisionReason`	`string`	PreToolUse	결정에 대해 Claude에게 표시되는 설명
`updatedInput`

이 예제는 /etc 디렉토리에 대한 쓰기 작업을 차단하면서 안전한 파일 관행에 대해 Claude에게 상기시키는 시스템 메시지를 주입합니다:

권한 결정 흐름

여러 훅 또는 권한 규칙이 적용될 때 SDK는 다음 순서로 평가합니다:

Deny 규칙이 먼저 확인됩니다 (매칭되면 즉시 거부).
Ask 규칙이 두 번째로 확인됩니다.
Allow 규칙이 세 번째로 확인됩니다.
아무것도 매칭되지 않으면 기본적으로 Ask입니다.

어떤 훅이든 deny를 반환하면 작업이 차단됩니다. 다른 훅이 allow를 반환해도 이를 재정의할 수 없습니다.

도구 차단

도구 실행을 방지하려면 거부 결정을 반환합니다:

도구 입력 수정

도구가 받는 내용을 변경하려면 업데이트된 입력을 반환합니다:

updatedInput을 사용할 때는 permissionDecision도 함께 포함해야 합니다. 원본 tool_input을 변경하지 말고 항상 새 객체를 반환하세요.

시스템 메시지 추가

대화에 컨텍스트를 주입합니다:

async def add_security_reminder(input_data, tool_use_id, context):
    return {
        'systemMessage': 'Remember to follow security best practices.'
    }

특정 도구 자동 승인

신뢰할 수 있는 도구에 대해 권한 프롬프트를 우회합니다. 특정 작업을 사용자 확인 없이 실행하려는 경우 유용합니다:

permissionDecision 필드는 세 가지 값을 허용합니다: 'allow' (자동 승인), 'deny' (차단) 또는 'ask' (확인 요청).

고급 시나리오 처리

이러한 패턴은 복잡한 사용 사례를 위한 더 정교한 훅 시스템을 구축하는 데 도움이 됩니다.

여러 훅 체이닝

훅은 배열에 나타나는 순서대로 실행됩니다. 각 훅을 단일 책임에 집중시키고 복잡한 로직을 위해 여러 훅을 체이닝하세요. 이 예제는 모든 도구 호출에 대해 네 개의 훅을 모두 실행합니다(매처 미지정):

정규식을 사용한 도구별 매처

정규식 패턴을 사용하여 여러 도구를 매칭합니다:

매처는 도구 이름만 매칭하며, 파일 경로나 다른 인수는 매칭하지 않습니다. 파일 경로로 필터링하려면 훅 콜백 내부에서 tool_input.file_path를 확인하세요.

서브에이전트 활동 추적

SubagentStop 훅을 사용하여 서브에이전트 완료를 모니터링합니다. tool_use_id는 부모 에이전트 호출과 서브에이전트를 연관시키는 데 도움이 됩니다:

훅에서의 비동기 작업

훅은 HTTP 요청과 같은 비동기 작업을 수행할 수 있습니다. 예외를 던지지 말고 캐치하여 오류를 우아하게 처리하세요. TypeScript에서는 signal을 fetch()에 전달하여 훅이 타임아웃되면 요청이 취소되도록 합니다:

알림 전송 (TypeScript 전용)

Notification 훅을 사용하여 에이전트로부터 상태 업데이트를 받고 Slack이나 모니터링 대시보드와 같은 외부 서비스로 전달합니다:

TypeScript

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

const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {
  const notification = input as NotificationHookInput;

  await fetch('https://hooks.slack.com/services/YOUR/WEBHOOK/URL', {
    method: 'POST',
    body: JSON.stringify({
      text: `Agent status: ${notification.message}`
    }),
    signal
  });

  return {};
};

for await (const message of query({
  prompt: "Analyze this codebase",
  options: {
    hooks: {
      Notification: [{ hooks: [notificationHandler] }]
    }
  }
})) {
  console.log(message);
}

일반적인 문제 해결

이 섹션에서는 일반적인 문제와 해결 방법을 다룹니다.

훅이 실행되지 않음

훅 이벤트 이름이 정확하고 대소문자가 구분되는지 확인하세요 (PreToolUse, preToolUse가 아님)
매처 패턴이 도구 이름과 정확히 일치하는지 확인하세요
훅이 options.hooks에서 올바른 이벤트 유형 아래에 있는지 확인하세요
SubagentStop, Stop, SessionStart, SessionEnd, Notification 훅의 경우 매처가 무시됩니다. 이러한 훅은 해당 유형의 모든 이벤트에 대해 실행됩니다.
세션이 훅이 실행되기 전에 종료되므로 에이전트가 max_turns 제한에 도달하면 훅이 실행되지 않을 수 있습니다

매처가 예상대로 필터링되지 않음

매처는 도구 이름만 매칭하며, 파일 경로나 다른 인수는 매칭하지 않습니다. 파일 경로로 필터링하려면 훅 내부에서 tool_input.file_path를 확인하세요:

const myHook: HookCallback = async (input, toolUseID, { signal }) => {
  const preInput = input as PreToolUseHookInput;
  const filePath = preInput.tool_input?.file_path as string;
  if (!filePath?.endsWith('.md')) return {};  // 마크다운이 아닌 파일 건너뛰기
  // 마크다운 파일 처리...
};

훅 타임아웃

HookMatcher 구성에서 timeout 값을 증가시키세요
TypeScript에서 세 번째 콜백 인수의 AbortSignal을 사용하여 취소를 우아하게 처리하세요

도구가 예기치 않게 차단됨

모든 PreToolUse 훅에서 permissionDecision: 'deny' 반환을 확인하세요
훅에 로깅을 추가하여 어떤 permissionDecisionReason을 반환하는지 확인하세요
매처 패턴이 너무 광범위하지 않은지 확인하세요 (빈 매처는 모든 도구와 매칭됩니다)

수정된 입력이 적용되지 않음

updatedInput이 최상위 수준이 아닌 hookSpecificOutput 내부에 있는지 확인하세요:

return {
  hookSpecificOutput: {
    hookEventName: input.hook_event_name,
    permissionDecision: 'allow',
    updatedInput: { command: 'new command' }
  }
};

입력 수정이 적용되려면 permissionDecision: 'allow'도 반환해야 합니다

세션 훅을 사용할 수 없음

SessionStart, SessionEnd, Notification 훅은 TypeScript SDK에서만 사용할 수 있습니다. Python SDK는 설정 제한으로 인해 이러한 이벤트를 지원하지 않습니다.

서브에이전트 권한 프롬프트 증가

여러 서브에이전트를 생성할 때 각각이 별도로 권한을 요청할 수 있습니다. 서브에이전트는 부모 에이전트의 권한을 자동으로 상속하지 않습니다. 반복적인 프롬프트를 피하려면 PreToolUse 훅을 사용하여 특정 도구를 자동 승인하거나, 서브에이전트 세션에 적용되는 권한 규칙을 구성하세요.

서브에이전트와의 재귀적 훅 루프

서브에이전트를 생성하는 UserPromptSubmit 훅은 해당 서브에이전트가 동일한 훅을 트리거하면 무한 루프를 생성할 수 있습니다. 이를 방지하려면:

생성 전에 훅 입력에서 서브에이전트 표시자를 확인하세요
parent_tool_use_id 필드를 사용하여 이미 서브에이전트 컨텍스트에 있는지 감지하세요
훅이 최상위 에이전트 세션에서만 실행되도록 범위를 지정하세요

systemMessage가 출력에 나타나지 않음

systemMessage 필드는 모델이 볼 수 있는 대화에 컨텍스트를 추가하지만, 모든 SDK 출력 모드에서 나타나지 않을 수 있습니다. 훅 결정을 애플리케이션에 표시해야 하는 경우 별도로 로깅하거나 전용 출력 채널을 사용하세요.

더 알아보기

권한: 에이전트가 할 수 있는 작업 제어
커스텀 도구: 에이전트 기능을 확장하는 도구 구축
TypeScript SDK 레퍼런스
Python SDK 레퍼런스

Stop

async def log_tool_calls(input_data, tool_use_id, context):
    if input_data['hook_event_name'] == 'PreToolUse':
        print(f"Tool: {input_data['tool_name']}")
        print(f"Input: {input_data['tool_input']}")
    return {}

async def block_etc_writes(input_data, tool_use_id, context):
    file_path = input_data['tool_input'].get('file_path', '')

    if file_path.startswith('/etc'):
        return {
            # 최상위 필드: 대화에 안내 주입
            'systemMessage': 'Remember: system directories like /etc are protected.',
            # hookSpecificOutput: 작업 차단
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Writing to /etc is not allowed'
            }
        }
    return {}

async def block_dangerous_commands(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PreToolUse':
        return {}

    command = input_data['tool_input'].get('command', '')

    if 'rm -rf /' in command:
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Dangerous command blocked: rm -rf /'
            }
        }
    return {}

async def redirect_to_sandbox(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PreToolUse':
        return {}

    if input_data['tool_name'] == 'Write':
        original_path = input_data['tool_input'].get('file_path', '')
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'allow',
                'updatedInput': {
                    **input_data['tool_input'],
                    'file_path': f'/sandbox{original_path}'
                }
            }
        }
    return {}

async def auto_approve_read_only(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PreToolUse':
        return {}

    read_only_tools = ['Read', 'Glob', 'Grep', 'LS']
    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 {}

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [
            HookMatcher(hooks=[rate_limiter]),        # 첫 번째: 속도 제한 확인
            HookMatcher(hooks=[authorization_check]), # 두 번째: 권한 확인
            HookMatcher(hooks=[input_sanitizer]),     # 세 번째: 입력 정제
            HookMatcher(hooks=[audit_logger])         # 마지막: 작업 기록
        ]
    }
)

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [
            # 파일 수정 도구 매칭
            HookMatcher(matcher='Write|Edit|Delete', hooks=[file_security_hook]),

            # 모든 MCP 도구 매칭
            HookMatcher(matcher='^mcp__', hooks=[mcp_audit_hook]),

            # 모든 것 매칭 (매처 없음)
            HookMatcher(hooks=[global_logger])
        ]
    }
)

async def subagent_tracker(input_data, tool_use_id, context):
    if input_data['hook_event_name'] == 'SubagentStop':
        print(f"[SUBAGENT] Completed")
        print(f"  Tool use ID: {tool_use_id}")
        print(f"  Stop hook active: {input_data.get('stop_hook_active')}")
    return {}

options = ClaudeAgentOptions(
    hooks={
        'SubagentStop': [HookMatcher(hooks=[subagent_tracker])]
    }
)

import aiohttp
from datetime import datetime

async def webhook_notifier(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PostToolUse':
        return {}

    try:
        async with aiohttp.ClientSession() as session:
            await session.post(
                'https://api.example.com/webhook',
                json={
                    'tool': input_data['tool_name'],
                    'timestamp': datetime.now().isoformat()
                }
            )
    except Exception as e:
        print(f'Webhook request failed: {e}')

    return {}