Cmd. /hooks

명령어 원본 선언

/hooks

공식 설명 요약

공식 문서의 정의는 "도구 이벤트에 대한 훅 설정을 조회한다(View hook configurations for tool events)"입니다.

/hooks는 읽기 전용 뷰어입니다. 현재 구성된 훅 이벤트와 각 이벤트에 걸린 훅 개수, 매처(matcher), 각 핸들러의 상세(command·prompt·URL)를 보여줍니다. 이 메뉴에서 훅을 추가·수정·삭제할 수는 없습니다. 훅을 실제로 바꾸려면 설정 JSON 파일(.claude/settings.json 등)을 직접 편집하거나 Claude에게 수정을 요청해야 합니다.

훅 자체는 Claude Code 수명주기의 특정 시점에 자동 실행되는 사용자 정의 셸 명령·HTTP 엔드포인트·LLM 프롬프트입니다. stdin(command 훅)이나 POST 본문(HTTP 훅)으로 JSON 컨텍스트를 받고, 동작을 차단·허용하는 결정을 돌려줍니다.

최소 지원 버전

• 명령 자체는 초기 내장 항목이며, Changelog에 /hooks 명령의 최초 도입 버전이 따로 적혀 있지 않습니다.
• 공식 명령 레퍼런스에는 별칭(alias)·제거·이름 변경 표기가 없습니다. 아래 사용 예에 적은 개별 훅 기능들의 도입 버전은 Changelog 기준입니다.

사용법

/hooks

/hooks는 인자를 받지 않습니다. 실행하면 구성된 훅을 이벤트별로 나열한 읽기 전용 메뉴가 열립니다.

좋은 사용 예

1. 현재 어떤 이벤트에 어떤 훅이 걸려 있는지 한눈에 점검
2. 매처가 의도한 도구(예: Bash, Edit|Write, mcp__memory__.*)에만 매칭되는지 확인
3. command/HTTP/prompt 핸들러의 실제 설정값과 URL 검토
4. InstructionsLoaded 훅으로 CLAUDE.md 로드 시 커스텀 동작 실행 (v2.1.69)
5. HTTP hooks로 외부 URL에 JSON POST하고 JSON 응답 수신 (v2.1.63) — 비-2xx·연결 실패·타임아웃은 비차단 에러로 처리되어 실행을 계속합니다
6. TeammateIdle/TaskCompleted hooks에서 {"continue": false, "stopReason": "..."} 응답으로 작업 중단 제어 (v2.1.69)

비슷한 명령어 추천

활용 사례

• 팀 공유 설정에 새 훅을 적용한 뒤 정상 등록 여부 확인
• PreToolUse 훅의 permissionDecision(allow/deny/ask/defer) 설정 검토
• SessionEnd·Stop 등 종료 계열 훅이 의도대로 걸려 있는지 점검

주의사항

• /hooks는 조회 전용이므로, 훅을 바꾸려면 설정 JSON을 편집하거나 Claude에게 수정을 요청해야 합니다.
• 자동화 실패 시 수동 fallback 경로를 문서화하고, 훅 실행 비용·시간을 모니터링하세요.
• PreToolUse 훅은 hookSpecificOutput.permissionDecision으로 도구 실행을 제어합니다 — allow(승인), deny(차단), ask(사용자 확인), defer(기본 권한 흐름 적용).
• v2.1.69에서 훅 이벤트 입력에 agent_id/agent_type/worktree 관련 필드가 추가되어 에이전트·워크트리를 구분할 수 있습니다.
• v2.1.77에서 PreToolUse 훅의 "allow" 반환이 deny 퍼미션 규칙을 우회하던 보안 버그가 수정되었습니다.
• v2.1.78에서 StopFailure 훅 이벤트가 추가되었습니다 — API 에러로 턴이 종료될 때 발생합니다.
• v2.1.78에서 ${CLAUDE_PLUGIN_DATA} 변수가 추가되었습니다 — 플러그인 업데이트에도 보존되는 영구 데이터 디렉터리 경로입니다.

# 예: SessionEnd 훅에 10초 여유 부여
export CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000

출처

• Claude Code Docs — Commands: https://code.claude.com/docs/en/commands
• Claude Code Docs — Hooks: https://code.claude.com/docs/en/hooks
• Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md