Claude Agent SDK 훅 실패 시 도구 실행 차단하기

AI 에이전트가 도구를 호출하기 전에 정책 검사 코드를 실행한다고 가정해 보자. 검사 코드가 예외를 내거나 잘못된 결과를 반환한다면 도구 호출은 어떻게 될까? 이때 실패한 검사를 통과로 취급하면 의도한 제어가 빠진 채 작업이 진행될 수 있다.

Anthropic이 2026년 11월 3일 공개한 Claude Agent SDK TypeScript 0.3.317은 훅 매처에 onFailure 옵션을 추가했다. 릴리스 설명에 따르면 "block"을 지정하면 훅이 예외를 던지거나 유효하지 않은 출력을 반환했을 때 해당 동작을 차단한다. 같은 날 공개된 Claude Code 2.1.317 변경 이력에도 Agent SDK 훅 콜백의 이 옵션이 포함됐다.

실패와 거절은 다르다

훅은 특정 이벤트에서 개발자가 작성한 콜백을 실행하는 연결 지점이다. 예를 들어 도구 실행 전 확인을 담당하는 훅을 둘 수 있다. 검사 결과가 정책 위반을 판정하는 경우와 검사 코드 자체가 실패하는 경우는 구분해야 한다. 새 옵션은 후자에 대한 처리 방식을 지정한다.

릴리스 설명에서 확인되는 범위는 명시적으로 onFailure: "block"을 설정한 훅이다. 모든 훅이 자동으로 차단 모드로 바뀐다는 뜻은 아니다. 또한 차단 여부는 훅이 적용되는 이벤트와 매처에 달려 있으므로, 실제 배포 환경에서 보호하려는 도구 호출이 해당 검사에 걸리는지 확인해야 한다.

운영에서 확인할 부분

업데이트 후에는 사용하는 SDK와 Claude Code 버전을 확인하고, 필요한 훅 매처에 옵션을 설정한 뒤 테스트 환경에서 콜백 예외와 잘못된 출력 각각을 재현해 보는 편이 좋다. 정상 승인과 정책 위반도 별도로 시험하면 실패 처리와 정책 판정이 뒤섞이지 않는다. 릴리스는 훅 콜백이 실패할 때 스트림에 경고 메시지도 추가했다고 설명한다. 운영자는 차단이 발생했을 때 경고를 수집하고 원인을 추적할 수 있는지도 살펴볼 수 있다.

차단 정책은 가용성과도 연결된다. 외부 서비스에 의존하는 검사에서 일시적인 장애가 발생하면 보호 대상 동작도 멈출 수 있다. 어떤 동작에 적용할지와 장애 복구 절차를 정한 다음 적용 범위를 넓히는 것이 안전하다. 이 글은 공식 릴리스 설명을 바탕으로 작성했으며 해당 동작을 별도 환경에서 재현하지는 않았다.

함께 바뀐 세션 저장 알림

SDK 0.3.317은 디스크가 가득 찼거나 할당량에 걸려 CLI가 세션 기록 또는 설정을 저장하지 못했을 때 마지막 결과 뒤에 session_writes_lost 시스템 메시지를 보내는 기능도 추가했다. 에이전트 실행 결과와 별개로 기록 저장에 실패했는지 확인하려는 운영자에게 유용한 신호다. 저장 실패 알림과 훅 차단은 서로 다른 기능이므로 각각의 이벤트를 따로 감시해야 한다.