에이전트 훅 설계: 차단·응답 변환·알림의 실행 계약
TECH INSIGHT / EXPLAINED
훅은 도구 실행 전 검사, 실행 후 알림, 응답 후처리를 코어 밖에서 연결하는 지점입니다. 효과는 이벤트 이름보다 '결과를 기다리는가, 실패하면 무엇을 하는가'라는 계약에서 결정됩니다.
차단·변환·관찰을 구분한다
pre_tool_use에서 권한을 판단한다면 결정이 끝나기 전에 도구를 실행하면 안 됩니다. pre_response에서 필수 문구를 붙이거나 민감정보를 제거한다면 전송 전에 결과를 기다려야 합니다. 반면 실행 후 통계와 선택적 알림은 별도 큐로 보낼 수 있습니다. 이벤트가 pre라는 이유만으로, 또는 응답이라는 이유만으로 일괄 비동기 처리하지 않습니다.
보안 판단의 오류·시간 초과·알 수 없는 반환값은 거부로 처리합니다. 선택적 분석 훅은 실패해도 진행할 수 있지만, 등록 시 중요도와 실패 정책을 명시하고 일반 확장이 필수 검사 정책을 완화하지 못하게 합니다.
셸 문자열 정규식은 격리 경계가 아니다
특정 삭제 명령 몇 개를 패턴으로 차단한다고 임의 명령 실행을 안전하게 만들 수는 없습니다. 가능한 작업을 구조화된 도구로 제한하고, 실행 파일·인자·경로의 허용 범위를 검사하세요. 명령 훅이 꼭 필요하면 데이터는 stdin이나 분리된 인자로 전달하고 최소 권한 프로세스로 실행합니다.
내장 JS 엔진도 연결해 준 파일·네트워크·호스트 함수에 따라 권한이 달라집니다. timeout context를 만들기만 해서는 무한 루프가 자동 종료되지 않을 수 있습니다. 런타임 중단 기능과 CPU·메모리·출력량 제한을 실제로 연결하고 시험해야 합니다.
수정 후 다시 검사한다
신뢰된 훅에만 제한된 입력 변경을 허용하더라도, 바뀐 최종 인자를 스키마·권한·범위 검사에 다시 통과시킵니다. 여러 훅의 순서와 충돌 규칙을 고정하고 hook 버전·event ID·변경된 필드 목록을 기록하세요. 테넌트 훅은 자기 범위 안에서만 등록·차단할 수 있습니다.
알림은 외부 부작용이다
비동기 알림에는 이벤트 저장, 재시도, 중복 식별, 최종 실패 상태가 필요합니다. 요청 ID 하나로 알림 중복을 줄일 수 있지만 외부 서비스가 멱등성을 제공하지 않으면 전송 성공 직후 연결 단절 같은 경우의 정확히 한 번 전달을 보장할 수 없습니다. '도구 호출됨'과 '실제 주문 체결됨' 알림도 구분합니다.
감사 로그도 개인정보다
입력 해시는 원문을 가리지만 사전 대입이나 동일값 연결로 정보를 추정할 수 있어 익명화 보장이 아닙니다. 필요한 필드만 남기고 민감값을 제거하며 보관 기간·조회 권한을 둡니다. dedup_key 컬럼을 만들었다는 사실만으로 중복이 막히지는 않으니 유일성 제약과 원자적 기록을 사용하세요.
필수 문구는 전송 직전 완성 응답을 검사하는 코드로 강제할 수 있습니다. 그래도 훅 오류·전송 오류·우회 경로가 있을 수 있으므로 100% 성공을 선언하기보다 실패를 검출하고 전달 상태를 기록하는 것이 검증 가능한 설계입니다.
참고 자료
내용·예제 검토: 2026-09-29
댓글
댓글 쓰기