ONEDEV

claude-code-hooks

AI Coding ToolsskillJavaScript

★ 512주당 +7조회 4

무엇인가

에이전트 자율성에 최소 권한을 강제하는 런타임 규율 계층이다. 셸 명령 실행, 파일 편집, 패키지 설치처럼 에이전트가 스스로 수행하는 동작을 사후 검토가 아니라 실행 시점에 허용·거부·수정하고, 그 사유를 에이전트에게 되돌려준다. 안전 규칙군은 .env와 비밀 값 유출, `curl | sh`, `rm -rf`, main 브랜치 강제 푸시, 훅 설정 자체의 변조를 막고, 나머지 규칙군은 자동화·알림·관측을 담당한다. 각 훅은 OWASP LLM Top 10 2026 항목에 대응시켜 분류돼 있다.

어떻게 동작하나

동작 단위는 Claude Code의 훅 이벤트다. SessionStart와 Stop/SessionEnd는 세션 경계에서 컨텍스트 주입과 결과 수집을 하고, UserPromptSubmit은 프롬프트 처리 전에 개입하며, PreToolUse는 도구 실행 전에 차단·수정하고, PostToolUse는 결과에 반응한다. Notification은 사용자 주의가 필요할 때, ConfigChange는 세션 중 설정 파일이 바뀔 때 발동한다. InstructionsLoaded는 CLAUDE.md나 `.claude/rules/*.md`가 컨텍스트에 로드될 때 발동하지만 결정 제어권이 없고 종료 코드도 무시되므로, 탐지와 강제를 분리해 같은 스크립트를 InstructionsLoaded·UserPromptSubmit·PreToolUse 세 곳에 등록하고 세션 락 파일로 차단을 유지한다. 각 플러그인은 스크립트·테스트·README를 담은 디렉터리로 배포되며, 기록 전용 훅은 비동기로 돌아 지연을 거의 더하지 않고 가드 훅은 거부가 도구 실행 전에 도달해야 하므로 동기로 남는다.

무엇과 다른가

CLAUDE.md·AGENTS.md에 규칙 문장을 적어 두는 방식과 구조가 다르다. 훅은 모델 바깥의 별도 프로세스로 실행되므로 프롬프트 인젝션이 규칙을 설득으로 우회할 수 없다. settings.json에 훅을 직접 작성하는 방식과도 다르다. 마켓플레이스 설치 한 줄로 스크립트·테스트·문서가 함께 들어오고, 설정 파일을 손으로 편집하지 않는다. config-guard는 PreToolUse에서 에이전트가 자기 가드레일을 다시 쓰는 것을 막고, config-watch는 ConfigChange에서 세션 중 다른 주체가 만든 변경을 감시한다. 보호 대상 파일의 신규 생성도 변조로 취급한다.

어떻게 쓰나

설치는 마켓플레이스를 한 번 등록한 뒤 필요한 플러그인만 지정한다. `/plugin marketplace add karanb192/claude-code-hooks` 실행 후 `/plugin install <plugin>@claude-code-hooks`를 쓰고 Claude Code를 재시작하면 활성화된다. 파일을 직접 소유하려면 `plugins/<name>/<name>.js`를 복사해 settings.json에 등록한다. 새 훅을 만들 때는 `event-logger.py`로 각 이벤트가 제공하는 데이터를 먼저 확인한다. config-guard를 켠 뒤에는 플러그인 관리 명령 자체가 막히므로 나머지 플러그인을 먼저 설치하거나 해당 호출에 `CONFIG_GUARD_ALLOW=true`를 준다.

전제와 한계

지원 대상은 Claude Code이며 훅 이벤트 모델을 갖춘 빌드가 전제다. InstructionsLoaded는 현재 빌드에서 `continue: false`조차 무시하므로 이 이벤트만으로는 강제가 성립하지 않는다. config-guard는 기본 high 수준에서 `claude plugin install/uninstall/disable`을 차단한다. 이전 `hook-scripts/` 경로를 settings.json이 가리키던 경우, 저장소를 갱신하면 경로가 사라지고 Claude Code는 실패한 훅 명령을 비차단 오류로 처리해 가드가 아무 표시 없이 작동을 멈춘다.

관련 논문 3

유사 도구