클로드 코드 훅이 끝내 알려주지 않는 6가지

여러 코딩 에이전트를 동시에 돌리는 사람이라면 한 번쯤 원하게 되는 화면이 있다. 어느 세션이 일하는 중이고, 어느 세션이 막혀 있으며, 어느 세션이 끝났는지 한눈에 보이는 목록이다. 터미널 기반 에이전트 관리 도구인 에이전트 매니저(agent-manager) 개발자가 클로드 코드(Claude Code)의 훅(hook) API로 이 목록을 만들다가 발견한 여섯 가지 사각지대를 공개했다. 자동화 파이프라인을 무인으로 돌리는 쪽이라면 남 얘기가 아니다.

무슨 일인가

에이전트 상태를 읽는 가장 흔한 방법은 화면을 긁는 것이다. 터미널 화면을 캡처해 정규식으로 훑는 방식인데, 어떤 CLI 도구에나 쓸 수 있다는 장점 대신 정확도를 포기해야 한다. 스피너가 한 프레임 사라지면 멈춘 것처럼 보이고, 스피너 비슷한 출력을 내는 도구는 일하는 것처럼 보인다.

클로드 코드에는 훅이 있으니 이 추측을 없앨 수 있어야 한다. 개발자는 관리 대상 세션마다 설정 파일을 생성해 실행 옵션으로 넘기고, 상태를 기록할 파일 경로를 환경 변수 하나로 전달했다. 각 훅은 그 파일에 단어 하나를 쓰는 한 줄짜리 셸 명령이다. 사용자 입력과 도구 호출 전후에는 작업 중, 정지 이벤트에는 완료, 세션 시작에는 대기, 세션 종료에는 파일 삭제가 대응한다. 폴러가 2초마다 그 파일을 읽는다. 여기까지는 정규식 추측 없이 정확하게 동작한다. 문제는 정상 경로를 벗어난 순간부터다.

핵심 짚어보기

공개된 여섯 가지 사각지대는 다음과 같다. 첫째, 알림 이벤트가 두 가지 의미로 쓰인다. 권한 승인 대기로 막혔을 때도 발생하지만, 입력창이 60초간 비어 있어도 재촉 알림으로 발생한다. 그대로 믿으면 자리를 비운 세션이 전부 막힌 상태로 표시된다. 개발자는 표준 입력으로 들어오는 페이로드를 검사해 재촉성 알림을 걸러 냈다.

둘째, 모델이 평문으로 질문을 던지며 턴을 끝내면 아무 이벤트도 발생하지 않는다. 훅 입장에서는 그냥 완료된 턴이라 목록에는 초록색 체크가 뜨지만, 실제로는 한 단어 답변을 기다리며 영원히 서 있는 세션이다. 셋째, Esc로 턴을 중단해도 정지 이벤트가 오지 않아 상태 파일은 작업 중에 고정된다. 사용자가 손대기 전까지 계속 틀린 상태는 상태가 없는 것보다 위험하다. 자리를 비운 채 목록을 믿는 상황이 정확히 그 경우다.

넷째, 정지 이벤트는 메인 루프 기준이다. 메인이 멈춰도 그가 띄운 백그라운드 에이전트는 계속 파일을 고칠 수 있어, 완료로 표시된 저장소가 검토 중에 바뀐다. 반대로 백그라운드 서브에이전트는 도구 호출 훅으로 작업 중만 쓰고 자기 종료 이벤트는 내지 않아, 보정하지 않으면 영원히 작업 중으로 남는다. 다섯째, 세션 시작 이벤트는 시작과 재개, 초기화뿐 아니라 컨텍스트 압축 시점에도 발생한다. 압축은 턴 도중에 일어나므로 매처를 명시하지 않으면 한창 일하는 세션 위에 대기 상태를 덮어쓴다. 여섯째, 크래시나 강제 종료에는 세션 종료 훅이 실행되지 않는다. 상태 파일이 프로세스보다 오래 살아남아 사라진 에이전트를 작업 중이라고 계속 보고한다.

결론은 절충이다. 훅을 1차 소스로 삼되 화면 판독을 폐기하지 않고 매 폴링마다 교차 검증한다. 완료라고 적힌 훅은 화면에 질문이나 오류, 진행 중인 작업이 보이면 그쪽으로 승격되고, 작업 중이라고 적힌 훅은 화면상 턴이 끝났으면 정정된다.

1인기업 실전 적용 포인트

• 크론으로 무인 실행하는 에이전트 작업에는 반드시 프로세스 생존 확인을 별도로 넣는다. 상태 파일이나 잠금 파일만 믿으면 죽은 작업이 실행 중으로 보여 다음 실행이 통째로 건너뛴다.
• 훅 명령에는 환경 변수 미설정 가드를 먼저 건다. 실패할 수 있는 훅은 언젠가 에이전트 자체를 멈춘다는 지적은 자동화 스크립트 전반에 그대로 적용된다.
• 완료 알림을 텔레그램 같은 채널로 받는다면 완료 신호를 그대로 신뢰하지 말고 산출물 파일의 존재와 크기, 갱신 시각을 함께 확인해 보고에 넣는다.
• 세션 시작 계열 이벤트는 매처를 시작, 재개, 초기화로 좁혀 압축 시점의 오탐을 막는다. 장시간 실행 작업일수록 압축은 반드시 일어난다.

전망과 주의점

이 사례가 남기는 교훈은 훅이 화면 판독을 대체하지 못하고 정확하게 만들어 줄 뿐이라는 점이다. 훅은 아무 출력도 없는 도구 호출처럼 화면이 보여 줄 수 없는 것을 알고, 화면은 질문과 중단, 오류처럼 훅이 이벤트를 내지 않는 것을 안다. 자동화 시스템의 신뢰도는 성공 경로가 아니라 실패 경로를 얼마나 정직하게 표시하느냐에서 갈린다. 해당 도구는 Go로 작성돼 아파치 2.0 라이선스로 공개돼 있으며, 클로드 코드와 코덱스, 오픈코드(OpenCode)를 나란히 띄우는 tmux 기반 터미널 UI다.

출처: agent-manager 개발 노트 (https://agent-manager.dev/writing/claude-code-hooks/)