3-4. Hook, 프롬프트·에이전트·비동기 훅과 보안 및 디버깅

프롬프트 기반 훅

명령어 및 HTTP 훅 외에도, Claude Code는 LLM을 사용하여 작업의 허용 또는 차단 여부를 평가하는 프롬프트 기반 훅(type: "prompt")과 도구 접근 권한을 가진 에이전트 검증기를 생성하는 에이전트 훅(type: "agent")을 지원합니다. 모든 이벤트가 모든 훅 유형을 지원하는 것은 아닙니다.

네 가지 훅 유형(command, http, prompt, agent)을 모두 지원하는 이벤트:

• PermissionRequest
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• UserPromptSubmit

type: "command" 훅만 지원하는 이벤트:

• ConfigChange
• InstructionsLoaded
• Notification
• PreCompact
• SessionEnd
• SessionStart
• SubagentStart
• TeammateIdle
• WorktreeCreate
• WorktreeRemove

프롬프트 기반 훅의 동작 방식

Bash 명령어를 실행하는 대신, 프롬프트 기반 훅은 다음과 같이 동작합니다:

1. 훅 입력과 프롬프트를 Claude 모델(기본값은 Haiku)에 전송합니다
2. LLM이 결정을 포함한 구조화된 JSON으로 응답합니다
3. Claude Code가 결정을 자동으로 처리합니다

프롬프트 훅 설정

type을 "prompt"로 설정하고 command 대신 prompt 문자열을 제공합니다. $ARGUMENTS 플레이스홀더를 사용하여 훅의 JSON 입력 데이터를 프롬프트 텍스트에 주입합니다. Claude Code는 결합된 프롬프트와 입력을 빠른 Claude 모델에 전송하고, 모델은 JSON 결정을 반환합니다.

이 Stop 훅은 Claude가 작업을 완료하기 전에 모든 작업이 완료되었는지 LLM에게 평가를 요청합니다:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

필드	필수 여부	설명
type	예	"prompt"여야 합니다
prompt	예	LLM에 전송할 프롬프트 텍스트. $ARGUMENTS를 훅 입력 JSON의 플레이스홀더로 사용합니다. $ARGUMENTS가 없으면 입력 JSON이 프롬프트 끝에 추가됩니다
model	아니오	평가에 사용할 모델. 기본값은 빠른 모델입니다
timeout	아니오	타임아웃(초 단위). 기본값: 30

응답 스키마

LLM은 다음을 포함하는 JSON으로 응답해야 합니다:

{
  "ok": true | false,
  "reason": "Explanation for the decision"
}

필드	설명
ok	true는 작업을 허용하고, false는 작업을 차단합니다
reason	ok가 false일 때 필수. Claude에게 표시되는 설명입니다

예시: 다중 조건 Stop 훅

이 Stop 훅은 Claude가 중지하기 전에 세 가지 조건을 확인하는 상세한 프롬프트를 사용합니다. "ok"가 false이면 Claude는 제공된 이유를 다음 지시사항으로 삼아 작업을 계속합니다. SubagentStop 훅도 동일한 형식을 사용하여 서브에이전트가 중지해야 하는지 평가합니다:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

에이전트 기반 훅

에이전트 기반 훅(type: "agent")은 프롬프트 기반 훅과 유사하지만 다중 턴 도구 접근 기능을 제공합니다. 단일 LLM 호출 대신, 에이전트 훅은 파일을 읽고, 코드를 검색하고, 코드베이스를 검사하여 조건을 검증할 수 있는 서브에이전트를 생성합니다. 에이전트 훅은 프롬프트 기반 훅과 동일한 이벤트를 지원합니다.

에이전트 훅의 동작 방식

에이전트 훅이 실행되면:

1. Claude Code가 프롬프트와 훅의 JSON 입력으로 서브에이전트를 생성합니다
2. 서브에이전트는 Read, Grep, Glob 같은 도구를 사용하여 조사할 수 있습니다
3. 최대 50턴 후, 서브에이전트가 구조화된 { "ok": true/false } 결정을 반환합니다
4. Claude Code는 프롬프트 훅과 동일한 방식으로 결정을 처리합니다

에이전트 훅은 훅 입력 데이터만으로는 부족하고, 실제 파일이나 테스트 출력을 검사해야 하는 검증에 유용합니다.

에이전트 훅 설정

type을 "agent"로 설정하고 prompt 문자열을 제공합니다. 설정 필드는 프롬프트 훅과 동일하며, 기본 타임아웃이 더 깁니다:

필드	필수 여부	설명
type	예	"agent"여야 합니다
prompt	예	검증할 내용을 설명하는 프롬프트. $ARGUMENTS를 훅 입력 JSON의 플레이스홀더로 사용합니다
model	아니오	사용할 모델. 기본값은 빠른 모델입니다
timeout	아니오	타임아웃(초 단위). 기본값: 60

응답 스키마는 프롬프트 훅과 동일합니다: { "ok": true }로 허용하거나 { "ok": false, "reason": "..." }로 차단합니다.

이 Stop 훅은 Claude가 작업을 완료하기 전에 모든 유닛 테스트가 통과하는지 검증합니다:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

백그라운드에서 훅 실행

기본적으로 훅은 완료될 때까지 Claude의 실행을 차단합니다. 배포, 테스트 스위트, 외부 API 호출 같은 장시간 실행 작업의 경우, "async": true를 설정하여 Claude가 계속 작업하는 동안 백그라운드에서 훅을 실행할 수 있습니다. 비동기 훅은 Claude의 동작을 차단하거나 제어할 수 없습니다: decision, permissionDecision, continue 같은 응답 필드는 효과가 없습니다. 제어 대상이었던 작업이 이미 완료되었기 때문입니다.

비동기 훅 설정

명령어 훅 설정에 "async": true를 추가하면 Claude를 차단하지 않고 백그라운드에서 실행됩니다. 이 필드는 type: "command" 훅에서만 사용할 수 있습니다.

이 훅은 매번 Write 도구 호출 후 테스트 스크립트를 실행합니다. Claude는 run-tests.sh가 최대 120초 동안 실행되는 동안 즉시 작업을 계속합니다. 스크립트가 완료되면 다음 대화 턴에서 출력이 전달됩니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true,
            "timeout": 120
          }
        ]
      }
    ]
  }
}

timeout 필드는 백그라운드 프로세스의 최대 실행 시간을 초 단위로 설정합니다. 지정하지 않으면 비동기 훅은 동기 훅과 동일한 10분 기본값을 사용합니다.

비동기 훅의 실행 방식

비동기 훅이 실행되면, Claude Code는 훅 프로세스를 시작하고 완료를 기다리지 않고 즉시 계속 진행합니다. 훅은 동기 훅과 동일하게 stdin을 통해 JSON 입력을 받습니다.

백그라운드 프로세스가 종료된 후, 훅이 systemMessage 또는 additionalContext 필드를 포함하는 JSON 응답을 생성했다면, 해당 내용은 다음 대화 턴에서 Claude에게 컨텍스트로 전달됩니다.

예시: 파일 변경 후 테스트 실행

이 훅은 Claude가 파일을 작성할 때마다 백그라운드에서 테스트 스위트를 시작하고, 테스트가 완료되면 결과를 Claude에게 보고합니다. 이 스크립트를 프로젝트의 .claude/hooks/run-tests-async.sh에 저장하고 chmod +x로 실행 권한을 부여하세요:

#!/bin/bash
# run-tests-async.sh

# Read hook input from stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Only run tests for source files
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Run tests and report results via systemMessage
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"
else
  echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"
fi

그런 다음 프로젝트 루트의 .claude/settings.json에 이 설정을 추가합니다. async: true 플래그를 사용하면 테스트가 실행되는 동안 Claude가 계속 작업할 수 있습니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

제한 사항

비동기 훅은 동기 훅에 비해 여러 가지 제약이 있습니다:

• type: "command" 훅만 async를 지원합니다. 프롬프트 기반 훅은 비동기적으로 실행할 수 없습니다.
• 비동기 훅은 도구 호출을 차단하거나 결정을 반환할 수 없습니다. 훅이 완료될 때쯤이면 트리거된 작업이 이미 진행된 상태입니다.
• 훅 출력은 다음 대화 턴에 전달됩니다. 세션이 유휴 상태이면 응답은 다음 사용자 상호작용까지 대기합니다.
• 각 실행은 별도의 백그라운드 프로세스를 생성합니다. 동일한 비동기 훅의 여러 실행 간 중복 제거는 수행되지 않습니다.

보안 고려사항

면책 조항

명령어 훅은 시스템 사용자의 전체 권한으로 실행됩니다.

주의: 명령어 훅은 사용자의 전체 권한으로 셸 명령어를 실행합니다. 사용자 계정이 접근할 수 있는 모든 파일을 수정, 삭제, 접근할 수 있습니다. 설정에 추가하기 전에 모든 훅 명령어를 검토하고 테스트하세요.

보안 모범 사례

훅을 작성할 때 다음 사항을 유의하세요:

• 입력 유효성 검사 및 정제: 입력 데이터를 맹목적으로 신뢰하지 마세요
• 셸 변수를 항상 따옴표로 감싸기: $VAR가 아닌 "$VAR"를 사용하세요
• 경로 순회 차단: 파일 경로에서 ..를 확인하세요
• 절대 경로 사용: 스크립트의 전체 경로를 지정하고, 프로젝트 루트에는 "$CLAUDE_PROJECT_DIR"를 사용하세요
• 민감한 파일 건너뛰기: .env, .git/, 키 파일 등을 피하세요

훅 디버깅

claude --debug를 실행하면 어떤 훅이 매칭되었는지, 종료 코드, 출력 등 훅 실행 세부 정보를 확인할 수 있습니다. Ctrl+O로 상세 모드를 전환하여 트랜스크립트에서 훅 진행 상황을 확인할 수 있습니다.

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 600000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

훅이 실행되지 않거나, 무한 Stop 훅 루프, 설정 오류 같은 일반적인 문제를 해결하려면 가이드의 제한 사항 및 문제 해결을 참조하세요.