클로드 코드 하위 에이전트 훅 — 신뢰 안 한 폴더는 조용히 건너뜀

하위 에이전트에도 훅을 달 수 있습니다. 그 에이전트가 도구를 쓰기 직전에 검사를 끼우거나, 파일을 고친 뒤 정리 도구를 돌리는 식이죠. 그런데 훅을 어디에 적었느냐에 따라 「도는 조건」이 완전히 달라집니다.

특히 성가신 건 정의 파일에 직접 적은 훅입니다. 그 폴더를 신뢰하기 전까지는 에이전트만 돌고 훅은 통째로 건너뜁니다. 화면에는 아무 말도 안 나오고요. 「분명 적어 뒀는데 왜 안 돌지」의 가장 흔한 원인입니다.

📌 30초 요약

• 훅을 두는 자리가 두 곳입니다.
• 앞머리 훅은 폴더 신뢰가 필요합니다.
• 안 믿은 폴더에선 대화상자도 안 뜹니다.
• 이름 짓기가 헐겁게 잡힙니다.
• 훅 끄기는 저장소가 되돌릴 수 있습니다.

1. 훅을 두는 두 자리

먼저 자리를 갈라 두겠습니다. 에이전트 정의 파일 맨 위에 적으면 그 에이전트가 활동하는 동안에만 돌고 끝나면 정리됩니다. 설정 파일에 적으면 세션 전체에 걸리고, 하위 에이전트 안에서도 그대로 발동합니다.

어디에 적나	언제 도나
정의 파일 앞머리	그 에이전트가 활동하는 동안만
설정 파일	세션 전체 — 하위 에이전트 안에서도
관리 정책·확장 묶음	마찬가지로 하위 에이전트 안까지
시작·종료 전용 이벤트	설정 파일에 적어야 본 세션에서 받음

앞머리 훅이 발동하는 경우는 생각보다 넓습니다. 도구로 띄울 때는 물론이고 골뱅이로 불러낼 때, 그리고 그 에이전트를 본 세션으로 띄워 쓸 때도 돕니다. 본 세션인 경우에는 설정 파일 훅과 나란히 돌고요. 한 가지 자동 변환도 있는데, 앞머리에 적은 「끝날 때」 훅은 하위 에이전트로 불릴 때 자동으로 「하위가 끝날 때」 이벤트로 바뀝니다. 훅의 기본 시점 구분을 알고 계시면 이 대응이 금방 잡힙니다.

2. 폴더를 믿어야 도는 훅

여기가 본론입니다. 저장소 안에 둔 에이전트의 앞머리 훅을 돌리려면 그 파일이 든 폴더의 신뢰 대화상자를 수락해야 합니다. 반면 내 개인 폴더에 둔 에이전트나 실행할 때 직접 넘긴 정의는 이 단계 없이 그냥 돕니다.

⚠️ 신뢰 전에는 말없이 건너뜁니다

폴더를 신뢰하기 전에도 하위 에이전트 자체는 정상으로 돕니다. 다만 앞머리 훅만 조용히 건너뛰고, 오류는 디버그 기록에만 남습니다. 화면에는 아무 표시도 없죠. 게다가 이 규칙은 설정 파일 훅보다 엄격해서, 부모 폴더를 신뢰한 것으로는 부족하고 한 번에 돌리는 방식은 아예 신뢰로 쳐주지 않습니다. 더 헷갈리는 건 이 경우 신뢰 대화상자가 아예 안 뜬다는 점입니다 — 물어보지도 않고 건너뛴다는 뜻이라, 사용자가 놓칠 수밖에 없습니다.

폴더를 따로 붙여 쓰실 때도 주의가 필요합니다. 신뢰한 작업 공간의 저장소 바깥에서 폴더를 추가했다면 그 폴더는 따로 신뢰해야 합니다 — 작업 공간에 준 허락이 상속되지 않습니다. 손으로 신뢰하는 길도 있는데, 설정 파일에서 해당 경로의 신뢰 수락 항목을 참으로 바꾸면 됩니다. 어떤 열쇠를 적어야 하는지는 건너뛴 훅에 대한 디버그 기록 줄이 정확히 찍어 줍니다.

예전에는 이렇지 않았습니다. 일정 판올림 이전에는 신뢰하지 않은 폴더에서도 앞머리 훅이 돌았고, 비대화형 실행에서도 그랬습니다. 남이 쓴 저장소를 열기만 해도 그 안의 스크립트가 돌 수 있었다는 뜻이죠. 권한 모드와 보호 경로를 함께 잡아 두면 이런 자리의 부담이 한 겹 줄어듭니다.

3. 이름이 헐겁게 잡히는 자리

설정 파일에는 하위 에이전트가 시작할 때와 끝날 때를 받는 전용 이벤트가 있습니다. 둘 다 에이전트 종류 이름으로 골라 걸 수 있어서, 특정 에이전트가 뜰 때만 준비 스크립트를 돌리고 아무나 끝나면 정리 스크립트를 돌리는 식으로 짤 수 있죠.

문제는 이름을 대조하는 방식입니다. 확장 묶음에서 온 에이전트는 이름에 쌍점이 들어가는데, 쌍점이 있으면 양끝이 고정되지 않은 표현식으로 평가합니다. 그래서 그 에이전트 하나만 잡으려면 앞뒤를 묶는 기호를 직접 붙여야 합니다. 안 그러면 이름에 그 조각이 들어간 다른 에이전트까지 함께 걸립니다.

붙임표가 든 이름에도 같은 함정이 있었습니다. 일정 판올림 이상에서만 정확히 일치하고, 그 이전 판에서는 마찬가지로 느슨하게 평가돼 앞에 뭔가 더 붙은 이름까지 함께 발동했습니다. 운영용 에이전트에 시험용 준비 스크립트가 딸려 도는 사고가 여기서 나옵니다. 이름을 붙이면 신분이 갈리는 문제와 함께 보면, 하위 에이전트에서 이름은 생각보다 무거운 값입니다.

4. 남의 저장소를 열기 전에

신뢰 규칙을 뒤집어 보면 「내가 안 쓴 저장소에서 무엇이 도는가」라는 질문이 됩니다. 신뢰를 안 해도 도는 것과 안 도는 것이 갈리니까요.

저장소가 들고 오는 것	부모만 신뢰했을 때
설정 파일의 훅·도우미	그냥 쓰입니다
허용 규칙·추가 폴더	안 쓰이고 대화상자가 다시 뜹니다
에이전트 앞머리 훅	안 쓰이고 대화상자도 없습니다
앞머리에 적은 연결 서버	안 쓰이고 대화상자도 없습니다

첫 줄과 셋째 줄의 비대칭이 이 표의 핵심입니다. 설정 파일에 적힌 훅은 부모 폴더만 믿어도 그냥 돌고, 에이전트 앞머리 훅은 안 돕니다. 「더 안쪽에 적었으니 더 잘 돌겠지」라는 짐작과 정반대죠. 그래서 남이 쓴 저장소를 여실 때는 설정 파일 쪽을 먼저 살펴보셔야 합니다.

막는 방법도 몇 가지 준비돼 있습니다. 설정을 읽어 오는 출처를 내 것으로 한정하거나, 헐벗은 모드로 시작해 훅·스킬·명령·에이전트·확장 묶음을 전부 안 읽게 할 수 있습니다. 다만 한 가지는 꼭 짚어야겠습니다 — 훅 전체를 끄는 값을 내 개인 설정에만 적어 두면 소용없습니다. 저장소의 프로젝트 설정이 내 설정보다 우선이라, 저장소가 그 값을 도로 켜 놓을 수 있습니다. 이 값은 훅을 다루는 다른 설정들과 달리 실행할 때 직접 넘겨야 확실합니다.

자주 묻는 질문 (FAQ)

Q. 앞머리에 훅을 적었는데 안 돕니다

그 파일이 든 폴더를 신뢰하셨는지 보세요. 신뢰 전에는 에이전트만 돌고 훅은 건너뛰며, 화면에 아무 표시가 없습니다. 디버그 기록에 사유와 함께 어떤 열쇠를 참으로 바꾸면 되는지까지 찍혀 있습니다.

Q. 부모 폴더를 신뢰했는데도 안 됩니다

앞머리 훅은 그 폴더 자체가 신뢰 대상입니다. 부모를 믿은 것은 쳐주지 않고, 폴더를 따로 붙여 쓰신 경우에도 그 폴더를 별도로 신뢰해야 합니다. 설정 파일에 적은 훅은 이와 달리 부모만 믿어도 돕니다.

Q. 특정 에이전트에만 걸었는데 다른 것도 걸립니다

이름 대조가 양끝이 고정되지 않은 표현식으로 평가되는 경우입니다. 쌍점이 든 확장 묶음 이름이 특히 그렇고, 붙임표가 든 이름도 예전 판에서는 느슨했습니다. 앞뒤를 묶는 기호를 직접 붙이세요.

Q. 훅을 전부 끄고 한 번만 돌리고 싶습니다

실행할 때 직접 넘기세요. 개인 설정에만 적으면 저장소의 프로젝트 설정이 도로 켤 수 있습니다. 아예 헐벗은 모드로 시작하면 훅뿐 아니라 스킬·명령·에이전트·확장 묶음을 모두 안 읽습니다.

정리하면

• 훅 자리는 두 곳입니다.
• 앞머리 훅은 폴더 신뢰가 조건입니다.
• 안 믿으면 묻지도 않고 건너뜁니다.
• 설정 파일 쪽이 더 헐겁습니다.
• 이름은 앞뒤를 묶어 적으세요.
• 훅 끄기는 실행할 때 넘기세요.

※ 공개된 하위 에이전트 문서와 권한 문서를 읽고 정리했습니다. 설정 항목과 실행 옵션 이름은 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 신뢰 규칙과 이름 대조 방식에는 최소 판올림 조건이 붙은 것이 있어, 쓰시는 판에 따라 동작이 다를 수 있습니다. 원문과 대조해 확인하세요.