PreToolUse 또는 PostToolUse? Claude Agent SDK에서 검사(check)를 어디에 배치해야 할까요

만약 에이전트가 비즈니스 액션을 트리거할 수 있다면, 가장 중요한 설계 질문은 각 검사가 어디서 실행되는지입니다. Claude Agent SDK에서는 모든 도구 호출 주변에 두 가지 지점의 훅(hook)을 제공합니다. 이 중 오직 하나만이 액션을 중단시킬 수 있습니다.

대부분의 설계를 결정하는 규칙

사이드 효과를 방지해야 하는 검사는 PreToolUse에 속해야 합니다. 이는 도구가 실행되기 전에 작동하여 결정을 반환합니다. PostToolUse는 실행 후에 작동합니다. 컨텍스트를 추가하거나, 에이전트가 보는 결과를 대체하거나, 이벤트를 기록할 수는 있지만, 이미 도구가 수행한 것을 되돌릴 수는 없습니다.

세 가지 PreToolUse 결정

PreToolUse 훅은 변경된 입력을 반환할 수도 있습니다. 이는 신중하게 사용하고 기록해야 합니다. 왜냐하면 그 경우 도구는 에이전트가 요청하지 않은 무언가를 실행하기 때문입니다.

두 가지 함정

비동기(Async) 훅은 게이트 역할을 할 수 없습니다. async: true (Python에서는 async_: True)를 반환하는 콜백은 도구를 차단하거나 그 입력을 변경할 수 없습니다. 액션을 제어하는 훅은 실행 전에 결정을 반환해야 합니다.

훅이 마지막 줄은 아닙니다. 훅이 비즈니스 레코드를 소유하는 것은 아닙니다. 도구 서비스는 권한 부여(authorization)와 비즈니스 검증을 반복해야 하며, 재시도 시 중복 생성을 막기 위해 Idempotency Key를 사용해야 합니다. 훅을 전달하는 것은 요청이 수용 가능해 보였다는 것을 보여줄 뿐, 액션 자체가 올바르다는 것을 의미하지 않습니다.

Agent SDK 훅은 Claude Code 훅과 다릅니다

이벤트 이름은 겹치지만, 소유자가 다릅니다. Agent SDK 훅은 Python의 ClaudeAgentOptions를 통해 또는 TypeScript의 SDK 옵션을 통해 에이전트를 실행하는 애플리케이션에 의해 등록됩니다. Claude Code 훅은 Claude Code 환경에서 구성됩니다. 시험 문제와 실제 사고 모두 이 차이를 활용합니다.

실제 사이드 효과가 발생하기 전 테스트 계획

실제 사이드 효과가 발생하기 전 테스트 계획

1. 유효하며, 제한치 미만의 요청을 보냅니다. 도구가 변경되지 않은 입력을 수신하는지 확인합니다.
2. 필수 필드를 제거하고, 공급업체를 변경하거나, 제한치를 초과시킵니다. 예상되는 거부 또는 질문이 발생하는지 확인합니다.
3. 조회 시간 초과(timeout), 도구 오류(tool error), 중복 요청을 시뮬레이션합니다. 각각의 경우 눈에 보이는 이벤트가 발생하며 의도하지 않은 동작은 없는지 확인합니다.
4. 로그가 불필요한 개인 데이터 없이 세션 ID, 도구 사용 ID, 결정 및 이유를 기록하는지 확인합니다.

성공적인 경로만큼이나 차단된 경로(blocked paths)도 신중하게 검토해야 합니다.

더 알아보기

• 전체 기사에서는 송장 승인 흐름을 다룹니다: Claude Agent SDK hooks on Timo Labs.
• 아키텍트 시험에서는 이를 task statement 1.5: Agent SDK hooks로 다룹니다.
• 무료 Claude Certified Architect 실습 시험으로 이러한 배치 결정을 연습해 보세요.