-p 플래그를 사용하는 비대화형 모드에서 Claude Code는 Agent SDK canUseTool 콜백처럼 프롬프트를 받을 권한 호스트가 실행에 있을 때만 AskUserQuestion과 ExitPlanMode를 제공합니다. 이 도구들은 사용자 상호 작용이 필요합니다. permissionDecision: "allow"와 updatedInput을 함께 반환하면 이 요구 사항이 충족됩니다. 훅은 stdin에서 도구의 입력을 읽고, 자체 UI를 통해 답변을 수집한 다음, updatedInput으로 반환하여 도구가 프롬프트 없이 실행되도록 합니다. 이 도구들에는 "allow"만 반환하는 것으로는 충분하지 않습니다. AskUserQuestion의 경우 원본 questions 배열을 그대로 돌려주고, 각 질문의 텍스트를 선택된 답변에 매핑하는 answers 객체를 추가합니다.

v2.1.199부터 서버가 _meta["anthropic/requiresUserInteraction"]으로 표시한 MCP 도구는 더 엄격합니다. Claude Code는 훅이 도구에 필요한 상호 작용을 수집했는지 확인할 수 없으므로, 훅은 updatedInput 유무와 관계없이 "allow"로 승인 프롬프트를 건너뛸 수 없습니다.

나중을 위해 도구 호출 지연

"defer"는 Agent SDK 앱이나 Claude Code 위에 구축된 사용자 지정 UI처럼 claude -p를 하위 프로세스로 실행하고 JSON 출력을 읽는 통합을 위한 것입니다. 이를 통해 호출 프로세스는 도구 호출 시점에서 Claude를 일시 중지하고, 자체 인터페이스를 통해 입력을 수집한 다음, 중단된 지점에서 재개할 수 있습니다. Claude Code는 -p 플래그를 사용하는 비대화형 모드에서만 이 값을 존중합니다. 대화형 세션에서는 경고를 로그에 기록하고 훅 결과를 무시합니다.

AskUserQuestion 도구가 대표적인 사례입니다. Claude는 사용자에게 무언가를 묻고 싶지만 답할 터미널이 없습니다. -p 실행은 --permission-prompt-tool로 전달하는 MCP 도구 같은 권한 호스트가 있을 때만 AskUserQuestion을 제공하므로, 권한 호스트와 함께 실행을 시작해야 합니다. 왕복 과정은 다음과 같습니다.

1. Claude가 AskUserQuestion을 호출합니다. PreToolUse 훅이 발생합니다.
2. 훅이 permissionDecision: "defer"를 반환합니다. 도구는 실행되지 않습니다. 프로세스는 stop_reason: "tool_deferred"로 종료되며, 보류 중인 도구 호출은 트랜스크립트에 보존됩니다.
3. 호출 프로세스는 SDK 결과에서 deferred_tool_use를 읽고, 자체 UI에 질문을 표시한 다음, 답변을 기다립니다.
4. 호출 프로세스는 같은 권한 호스트로 claude -p --resume <session-id>를 실행합니다. 같은 도구 호출이 다시 PreToolUse를 발생시킵니다.
5. 훅이 updatedInput에 답변을 담아 permissionDecision: "allow"를 반환합니다. 도구가 실행되고 Claude가 계속합니다.

deferred_tool_use 필드에는 도구의 id, name, input이 담깁니다. input은 Claude가 도구 호출을 위해 생성한 매개변수로, 실행 전에 캡처됩니다.

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

타임아웃이나 재시도 제한은 없습니다. 세션은 재개할 때까지 디스크에 남아 있으며, 보존 정리 규칙에 따라 기본적으로 30일 후 세션 파일을 삭제하는 cleanupPeriodDays 보존 정리의 적용을 받습니다. 재개할 때 답변이 준비되지 않았다면 훅은 다시 "defer"를 반환할 수 있으며, 프로세스는 같은 방식으로 종료됩니다. 호출 프로세스는 결국 훅에서 "allow" 또는 "deny"를 반환하여 루프를 끝낼 시점을 제어합니다.

"defer"는 Claude가 턴에서 단일 도구 호출을 할 때만 작동합니다. Claude가 한 번에 여러 도구 호출을 하면 "defer"는 경고와 함께 무시되고 도구는 일반 권한 흐름을 통해 진행됩니다. 이 제약은 재개 시 하나의 도구만 다시 실행할 수 있기 때문에 존재합니다. 배치에서 하나의 호출을 지연하면서 나머지를 해결되지 않은 상태로 두지 않을 방법이 없습니다.

재개할 때 지연된 도구를 더 이상 사용할 수 없으면 프로세스는 훅이 발생하기 전에 stop_reason: "tool_deferred_unavailable" 및 is_error: true로 종료됩니다. 이는 도구를 제공한 MCP 서버가 재개된 세션에 연결되어 있지 않을 때 발생합니다. deferred_tool_use 페이로드는 여전히 포함되므로 어떤 도구가 없어졌는지 식별할 수 있습니다.

PermissionRequest

Claude Code가 도구 사용 권한을 요청하려고 할 때 실행됩니다. 비대화형 모드의 백그라운드 서브에이전트처럼 프롬프트를 표시할 수 없는 세션에서도 Claude Code는 이 훅을 실행하며, 어떤 훅도 결정을 반환하지 않으면 도구 호출을 거부합니다. 사용자를 대신하여 허용하거나 거부하려면 PermissionRequest 결정 제어를 사용합니다.

Claude가 도구 사용 권한을 요청하는 순간에 신호가 필요할 때 이 이벤트를 사용합니다. Claude Code는 프롬프트가 약 6초 동안 대기한 후에만 permission_prompt 유형의 Notification 훅을 실행합니다.

Claude Code는 샌드박스 처리된 명령의 네트워크 요청에 대해서는 PermissionRequest 훅을 실행하지 않습니다. 해당 프롬프트에 대한 신호를 받으려면 permission_prompt 알림 유형을 사용합니다.

PreToolUse와 같은 값으로 도구 이름에 대해 일치시킵니다.

PermissionRequest 입력

PermissionRequest 훅은 PreToolUse 훅처럼 tool_name과 tool_input 필드를 받지만 tool_use_id는 받지 않습니다. MCP 도구의 경우 mcp_server 객체도 받습니다. 선택적 permission_suggestions 배열에는 허용 규칙 추가나 권한 모드 변경처럼 Claude Code가 이 요청에 대해 제안하는 권한 업데이트가 담깁니다.

각 권한 대화 상자는 자체 옵션을 구성하므로 permission_suggestions 배열은 사용자에게 표시되는 옵션의 정확한 목록이 아닙니다. 파일 편집용 대화 상자처럼 일부 대화 상자는 배열을 전혀 읽지 않고 요청 자체에서 옵션을 도출합니다. 배열을 읽는 대화 상자도 제안이 배열에 남아 있는 옵션을 보류할 수 있습니다. 예를 들어 allowManagedPermissionRulesOnly가 규칙 저장 옵션을 숨기는 경우입니다. 또한 권한 업데이트를 통하지 않고 권한 모드를 직접 변경하는 Yes, and switch to auto mode처럼 제안 항목이 없는 옵션을 제공할 수도 있습니다.

PreToolUse 훅은 권한이 필요한지 여부와 관계없이 모든 도구 호출 전에 실행됩니다. PermissionRequest 훅은 Claude Code가 권한을 요청하려고 할 때, 또는 프롬프트를 표시할 수 없는 호출을 자동 거부하려고 할 때만 실행됩니다. 두 이벤트 모두 EndConversation에서는 발생하지 않습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

PermissionRequest 결정 제어

PermissionRequest 훅은 권한 요청을 허용하거나 거부할 수 있습니다. 모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 훅 스크립트는 다음 이벤트별 필드가 있는 decision 객체를 반환할 수 있습니다.

decision 객체 없이 종료 코드 2로 종료하는 훅은 권한 흐름을 변경하지 않으며, stderr는 버려집니다. decision 객체만 요청을 허용하거나 거부할 수 있습니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

권한 업데이트 항목

updatedPermissions 출력 필드와 permission_suggestions 입력 필드는 모두 같은 항목 객체 배열을 사용합니다. 각 항목에는 다른 필드를 결정하는 type과 변경 사항이 기록되는 위치를 제어하는 destination이 있습니다.

모든 항목의 destination 필드는 변경 사항을 메모리에만 유지할지 설정 파일에 저장할지를 결정합니다.

훅은 전달받은 permission_suggestions 중 하나를 그대로 자신의 updatedPermissions 출력으로 반환할 수 있습니다.

PostToolUse

도구가 성공적으로 완료된 직후에 실행됩니다.

도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.

도구 이름이 적절한 필터가 아닐 때는 더 넓게 매칭할 수 있습니다.

• 어떤 도구든 성공적으로 완료된 후에 훅을 실행하려면 matcher를 생략하거나 "*"로 설정합니다. 그러면 훅이 무엇이 변경되었는지 직접 파악할 수 있습니다. 예를 들어 git status --porcelain을 실행하면 git diff가 놓치는 추적되지 않은 파일도 함께 나열됩니다. 실패한 도구 호출의 경우 같은 훅을 PostToolUseFailure 아래에 추가합니다.
• 무엇이 파일을 기록했는지와 관계없이 특정 파일이 디스크에서 변경될 때 훅을 실행하려면 FileChanged를 사용합니다. Bash 명령이나 Claude Code 외부의 프로세스가 같은 파일을 다시 쓰는 경우, Claude Code는 Edit|Write에 매칭되는 PostToolUse 훅을 실행하지 않습니다.

PostToolUse 입력

PostToolUse 훅은 도구가 이미 성공적으로 실행된 후에 발생합니다. 입력에는 도구에 전송된 인수인 tool_input과 도구가 반환한 결과인 tool_response가 모두 포함됩니다. 두 필드의 정확한 스키마는 도구에 따라 다릅니다. 파일 도구의 tool_input 경로는 PreToolUse와 같은 형식으로 전달됩니다. 즉, 항상 절대 경로이며 플랫폼 고유의 구분자를 사용하므로 Windows에서는 백슬래시가 사용됩니다. MCP 도구의 경우 입력에 mcp_server 객체도 포함됩니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

PostToolUse 결정 제어

PostToolUse 훅은 도구 실행 후 Claude에게 피드백을 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

아래 예시는 Bash 호출의 출력을 대체합니다. 대체 값은 Bash 도구의 출력 형태와 일치합니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

자동 모드 분류기를 위한 결과 주석 달기

classifierContext를 반환하면 도구 호출 결과에 대한 짧은 메모를 Claude가 아닌 자동 모드 분류기에 전송합니다. 분류기는 도구 결과 자체를 전달받지 않으므로, 이 필드는 분류기가 이후 작업을 검토하기 전에 호출이 반환한 내용에 대해 알려 줄 수 있는 공식적인 방법입니다. 이 필드는 Claude Code v2.1.236 이상이 필요합니다.

아래 예시는 쿼리 출력의 출처를 분류기에 알려 줍니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

분류기가 메모에 부여하는 가중치는 훅을 어디에서 구성했는지에 따라 달라집니다.

• Claude Code에서 구성한 훅: 설정 파일, 플러그인, 스킬, 에이전트 frontmatter에서 온 훅의 경우, 분류기는 메모를 검증되지 않은 애플리케이션 제공 컨텍스트로 취급합니다. 메모는 사용자 의도를 확립하지 않으며, 메모에서 사용자가 무언가를 승인하거나 요청했다고 주장하는 경우 분류기는 대화에 있는 사용자의 실제 메시지와 대조하여 그 주장을 확인합니다
• 프로세스 내 Agent SDK 콜백: Claude Code를 내장한 애플리케이션이 훅을 TypeScript SDK 콜백으로 등록하고 실행 중인 세션에서 메모를 반환하는 경우, 분류기는 메모에 전달된 사용자 발언을 사용자 의도로 고려할 수 있습니다. 이러한 발언은 분류기가 사용자가 보낸 메시지로부터 수용할 수 있는 동의 요건을 충족할 수 있지만, 사용자 자신의 메시지로도 해제할 수 없는 차단을 해제하지는 않습니다. 세션이 재개된 후에는 Claude Code가 복원된 메모를 검증되지 않은 컨텍스트로 취급합니다. 두 그룹의 훅이 같은 호출에 주석을 다는 경우, 분류기는 결합된 메모를 검증되지 않은 것으로 취급합니다

Claude Code는 메모를 전달할 때 다음과 같은 제한을 적용합니다.

• 길이: Claude Code는 하나의 도구 호출에 대한 메모를 2,000자로 제한하고 나머지는 잘라냅니다. 이 제한은 해당 호출에 응답하는 모든 훅이 공유합니다
• 동기 응답만 해당: 백그라운드에서 실행되는 훅의 응답은 Claude Code가 도구 결과를 기록한 후에 도착하므로, Claude Code는 이러한 응답의 필드를 무시합니다
• 분류기가 기록하지 않는 호출: 분류기의 트랜스크립트는 파일 읽기 및 검색과 같은 읽기 전용 조회를 생략합니다. Claude Code는 이러한 호출에 첨부된 메모를 삭제합니다
• 재작성과의 상호작용: 메모가 updatedToolOutput으로 대체하는 출력을 설명하는 경우, 같은 훅 응답에서 두 필드를 모두 반환합니다. 해당 재작성이 거부되거나 다른 훅의 재작성이 이를 대체하면 Claude Code는 메모를 삭제합니다. 재작성 없이 반환한 메모는 다른 훅이 출력을 재작성하더라도 Claude Code가 전달합니다

PostToolUseFailure

실행을 시작한 도구가 실패할 때 실행됩니다. 즉, 도구에서 오류가 발생했거나 MCP 도구가 오류 결과를 반환한 경우입니다. 실패를 로그에 기록하거나, 알림을 보내거나, Claude에게 수정 피드백을 제공하는 데 사용합니다.

도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.

PostToolUseFailure 입력

PostToolUseFailure 훅은 PostToolUse와 같은 tool_name 및 tool_input 필드와 함께 최상위 필드로 오류 정보를 전달받습니다. MCP 도구의 경우 mcp_server 객체도 전달받습니다. 예를 들어 실패한 npm test 명령은 다음을 전달할 수 있습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

error 문자열은 일반적으로 Claude가 실패한 도구의 결과로 받는 텍스트와 같습니다. 형식은 도구와 실패 유형에 따라 다릅니다. 훅은 tool_name, is_interrupt, 첫 줄의 Exit code N을 기준으로 동작하도록 작성하고, 문자열의 나머지 부분은 안정적인 형식이 아닌 표시용 텍스트로 취급합니다.

• Bash와 PowerShell의 경우, 실행된 후 종료된 명령은 첫 줄에 Exit code N을 생성하고, 그 뒤에 명령이 생성한 출력을 stdout과 stderr가 섞인 하나의 블록으로 생성합니다
• Claude Code가 셸 프로세스 자체를 시작할 수 없었던 경우, 페이로드에 종료 코드 줄 없이 실패 메시지만 포함될 수도 있습니다
• Claude Code는 긴 문자열의 중간 부분을 ... [N characters truncated] ... 마커를 기준으로 잘라내며, Command timed out after 2m 0s와 같은 자체 줄을 삽입할 수 있습니다

PostToolUseFailure 결정 제어

PostToolUseFailure 훅은 도구 실패 후 Claude에게 컨텍스트를 제공할 수 있습니다. 모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

PostToolBatch

배치의 모든 도구 호출이 처리된 후, Claude Code가 모델에 다음 요청을 보내기 전에 한 번 실행됩니다. PostToolUse는 도구마다 한 번씩 발생하므로, Claude가 병렬 도구 호출을 수행하면 동시에 발생합니다. PostToolBatch는 전체 배치에 대해 정확히 한 번 발생하므로, 단일 도구가 아닌 실행된 도구 집합에 따라 달라지는 컨텍스트를 주입하기에 적합한 위치입니다. 이 이벤트에는 matcher가 없습니다.

PostToolBatch 입력

공통 입력 필드 외에도 PostToolBatch 훅은 배치의 모든 도구 호출을 설명하는 배열인 tool_calls를 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

tool_response에는 모델이 해당 tool_result 블록에서 받는 것과 같은 내용이 포함됩니다. 값은 도구가 내보낸 그대로의 직렬화된 문자열 또는 콘텐츠 블록 배열입니다. Read의 경우 원시 파일 내용이 아니라 줄 번호가 앞에 붙은 텍스트입니다. 응답이 클 수 있으므로 필요한 필드만 파싱합니다.

PostToolBatch 결정 제어

PostToolBatch 훅은 Claude를 위한 컨텍스트를 주입할 수 있습니다. 모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

decision: "block" 또는 continue: false를 반환하면 다음 모델 호출 전에 에이전틱 루프가 중지됩니다. 차단 메시지는 JSON의 reason 또는 stopReason에서 가져오거나, 종료 코드 2인 경우 stderr에서 가져옵니다. 이 메시지는 트랜스크립트에 경고로 표시되며 대화에 남아 있으므로, 대화가 계속되면 Claude가 이를 보게 됩니다.

PermissionDenied

자동 모드가 도구 호출을 거부할 때 실행됩니다. 여기에는 자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부했거나 분류기의 응답을 파싱할 수 없어서 분류기 판정 없이 거부한 경우도 포함됩니다. 이 훅은 자동 모드에서만 발생합니다. 사용자가 권한 대화 상자에서 직접 거부하거나, PreToolUse 훅이 호출을 차단하거나, deny 규칙이 매칭되는 경우에는 실행되지 않습니다. 거부를 로그에 기록하거나, 구성을 조정하거나, 모델에게 도구 호출을 재시도해도 된다고 알리는 데 사용합니다.

도구 이름으로 매칭하며, 값은 PreToolUse와 같습니다.

PermissionDenied 입력

공통 입력 필드 외에도 PermissionDenied 훅은 tool_name, tool_input, tool_use_id, reason을 전달받습니다. MCP 도구의 경우 mcp_server 객체도 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

PermissionDenied 결정 제어

PermissionDenied 훅은 모델에게 거부된 도구 호출을 재시도해도 된다고 알릴 수 있습니다. hookSpecificOutput.retry를 true로 설정한 JSON 객체를 반환합니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

retry가 true이면 Claude Code는 모델에게 도구 호출을 재시도해도 된다고 알리는 메시지를 대화에 추가합니다. Claude Code가 거부 자체를 번복하지는 않습니다. 훅이 JSON을 반환하지 않거나 retry: false를 반환하면 거부가 유지되고 모델은 원래의 거부 메시지를 받습니다.

분류기가 작업에 대한 판정을 내리지 못한 경우, 즉 분류기의 응답을 파싱할 수 없었거나 자동 모드와 별개인 안전 검사가 분류기 자체의 요청을 거부한 경우 Claude Code는 retry: true를 무시합니다. 이러한 거부의 경우 Claude Code는 이미 거부 메시지에서 모델에게 나중에 재시도할지 다음으로 넘어갈지 알려 줍니다.

Notification

Claude Code가 알림을 보낼 때 실행됩니다. 알림 유형으로 매칭합니다. 모든 알림 유형에 대해 훅을 실행하려면 matcher를 생략합니다.

데스크톱 알림을 꺼 두어도 이 훅 이벤트는 전달됩니다. notifications_disabled를 포함한 preferredNotifChannel 설정은 사용자에게 알리는 방식만 변경할 뿐 훅의 실행 여부에는 영향을 주지 않습니다.

quota_auto_resume_fired, quota_auto_resume_stale, quota_auto_resume_disabled 유형은 Claude Code v2.1.234 이상이 필요합니다.

터미널 세션에서 샌드박스 처리된 명령의 네트워크 요청에 대한 permission_prompt는 Claude Code v2.1.246 이상이 필요합니다.

팀원의 터미널 설정 질문에 대한 agent_needs_input은 Claude Code v2.1.248 이상이 필요합니다.

Claude Code가 권한 요청을 Agent SDK의 canUseTool 콜백으로 보내는 세션에서는 permission_prompt의 타이밍이 다릅니다. Claude Desktop과 VS Code 확장 프로그램이 이 방식으로 Claude Code를 호스팅합니다.

• permission_prompt는 Claude가 권한을 요청한 후 약 6초가 지나면 발생합니다. 사용자가 입력하는 동안에도 Claude Code는 이를 연기하지 않습니다.
• 사용자나 PermissionRequest 훅이 더 일찍 응답하면 Claude Code는 permission_prompt를 실행하지 않습니다.
• 이러한 세션에서 permission_prompt를 끄려면 CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS를 1로 설정합니다.

v2.1.233 이전에는 이러한 세션에서 permission_prompt가 발생하지 않았습니다.

알림 유형에 따라 서로 다른 핸들러를 실행하려면 별도의 matcher를 사용합니다. 다음 구성은 Claude가 권한 승인을 필요로 할 때 권한 전용 알림 스크립트를 트리거하고, Claude가 유휴 상태일 때 다른 알림을 트리거합니다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Notification 입력

공통 입력 필드 외에도 Notification 훅은 알림 텍스트가 담긴 message, 선택적 title, 발생한 유형을 나타내는 notification_type을 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Notification 훅은 알림을 차단하거나 수정할 수 없습니다. Claude Code는 이 훅의 systemMessage 및 continue 필드를 삭제하지만, 데스크톱 알림 예시가 사용하는 terminalSequence는 계속 내보냅니다. Notification 훅은 알림을 외부 서비스로 전달하는 것과 같은 부수 효과를 위한 것입니다.

SubagentStart

Claude가 Agent 도구로 서브에이전트를 생성할 때, Claude가 서브에이전트를 재개할 때, 그리고 프로세스 내 에이전트 팀 팀원이 새 메시지를 처리할 때마다 실행됩니다. 에이전트 유형 이름으로 필터링하는 matcher를 지원합니다. 기본 제공 에이전트의 경우 general-purpose, Explore, Plan과 같은 에이전트 이름입니다. 사용자 정의 서브에이전트의 경우 파일 이름이 아니라 에이전트 frontmatter의 name 필드입니다.

플러그인으로 제공되는 서브에이전트의 경우 에이전트 유형은 단순한 frontmatter 이름이 아니라 my-plugin:reviewer와 같은 플러그인 범위 식별자입니다. 콜론이 있으면 플러그인 범위 이름이 정규식 경로로 처리되므로, 정확히 매칭하려면 matcher를 ^와 $로 고정합니다: ^my-plugin:reviewer$.

SubagentStart 입력

공통 입력 필드 외에도 SubagentStart 훅은 서브에이전트의 고유 식별자가 담긴 agent_id와 matcher가 필터링하는 에이전트 이름이 담긴 agent_type을 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

SubagentStart 훅은 서브에이전트 생성을 차단할 수 없지만, 서브에이전트에 컨텍스트를 주입할 수 있습니다. 모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 다음을 반환할 수 있습니다.

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

같은 서브에이전트에 대해 훅이 다시 실행되면, Claude Code는 서브에이전트의 컨텍스트에 이전 실행의 사본이 아직 없는 경우에만 반환된 컨텍스트를 주입합니다. 시작 시 주입된 사본은 그대로 유지되므로 서브에이전트의 프롬프트 캐시가 손상되지 않습니다. 자동 압축으로 해당 사본이 삭제된 후에는 Claude Code가 다음 실행의 컨텍스트를 다시 주입합니다.

SubagentStop

Claude Code 서브에이전트가 응답을 마쳤을 때 실행됩니다. 에이전트 유형으로 매칭하며, 값은 SubagentStart와 같습니다.

SubagentStop 입력

공통 입력 필드 외에도 SubagentStop 훅은 stop_hook_active, agent_id, agent_type, agent_transcript_path, last_assistant_message를 전달받습니다. agent_type 필드는 matcher 필터링에 사용되는 값입니다. transcript_path는 메인 세션의 트랜스크립트이고, agent_transcript_path는 중첩된 subagents/ 폴더에 저장된 서브에이전트 자체의 트랜스크립트입니다. last_assistant_message 필드에는 서브에이전트의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다.

모든 SubagentStop 이벤트가 Claude가 생성한 서브에이전트에서 오는 것은 아닙니다. Claude Code는 프롬프트 제안 및 /btw 곁가지 질문과 같은 일부 자체 기능을 위해 내부 에이전트도 실행하며, 이러한 에이전트 중 하나가 완료될 때도 SubagentStop이 발생합니다. 이러한 이벤트의 경우 agent_type은 --agent 또는 agent 설정으로 지정된 것처럼 세션 자체가 실행되는 에이전트 이름이며, 세션이 에이전트 없이 실행되는 경우 빈 문자열입니다.

에이전트 유형을 지정하는 matcher는 빈 agent_type과 매칭되지 않습니다. matcher가 생략되었거나, "" 또는 "*"이거나, 빈 문자열과 매칭되는 정규식인 훅은 빈 agent_type을 가진 이벤트에서도 실행됩니다.

Claude Code v2.1.271 이상에서는 SubagentHandback 도구와 함께 실행되는 서브에이전트가 중지되기 전에 해당 도구를 통해 보고서를 전달합니다. 이 경우 last_assistant_message 필드에는 서브에이전트의 마무리 텍스트(있는 경우)가 담기며, 이는 전달된 보고서가 아닙니다. 보고서는 해당 호출의 message 입력이며, SubagentHandback에 매칭되는 PreToolUse 또는 PostToolUse 훅이 이를 tool_input.message로 전달받습니다.

SubagentStop 훅은 Stop 입력에서 설명하는 background_tasks 및 session_crons 배열도 전달받습니다. 두 배열 모두 서브에이전트가 아닌 부모 세션 범위입니다.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

SubagentStop 훅은 Stop 훅과 같은 결정 제어 형식을 사용하며, 여기에는 서브에이전트를 계속 실행시키는 오류가 아닌 피드백을 위해 hookEventName을 "SubagentStop"으로 설정한 hookSpecificOutput.additionalContext도 포함됩니다. reason과 함께 decision: "block"을 반환하면 서브에이전트가 계속 실행되며 reason이 서브에이전트의 다음 지시로 전달됩니다. 종료 코드 2로 차단하는 훅도 같은 방식으로 stderr 메시지를 전달합니다. 서브에이전트가 반환된 후 부모 세션에 컨텍스트를 주입하려면 대신 Agent 도구에 대한 PostToolUse 훅을 사용합니다.

TaskCreated

TaskCreate 도구를 통해 작업이 생성될 때 실행됩니다. 명명 규칙을 적용하거나, 작업 설명을 필수로 요구하거나, 특정 작업이 생성되지 않도록 막는 데 사용합니다. Task 도구가 없는 세션에서는 이 이벤트가 발생하지 않습니다.

TaskCreated 훅은 matcher를 지원하지 않으며 매번 발생합니다.

TaskCreated 입력

공통 입력 필드 외에도 TaskCreated 훅은 task_id, task_subject와 선택적으로 task_description, teammate_name, team_name을 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCreated 결정 제어

TaskCreated 훅은 두 가지 방법으로 생성을 차단할 수 있습니다. 어느 방법이든 Claude Code는 작업을 삭제하고 메시지를 도구의 오류로 Claude에게 반환합니다. Claude Code는 이 이벤트의 continue: false를 무시하며 Claude는 계속 작업합니다.

• 종료 코드 2: Claude Code가 stderr 텍스트를 메시지로 반환합니다.
• JSON {"decision": "block", "reason": "..."}: Claude Code가 reason을 메시지로 반환합니다.

이 예시는 제목이 필수 형식을 따르지 않는 작업을 차단합니다.

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

작업이 완료로 표시될 때 실행됩니다. 이 이벤트는 두 가지 상황에서 발생합니다. 어떤 에이전트든 TaskUpdate 도구를 통해 작업을 명시적으로 완료로 표시하는 경우, 또는 에이전트 팀 팀원이 진행 중인 작업이 있는 상태에서 턴을 마치는 경우입니다. 작업이 종료되기 전에 테스트 통과나 린트 검사와 같은 완료 기준을 적용하는 데 사용합니다.

TaskCompleted 훅은 matcher를 지원하지 않으며 매번 발생합니다.

TaskCompleted 입력

공통 입력 필드 외에도 TaskCompleted 훅은 task_id, task_subject와 선택적으로 task_description, teammate_name, team_name을 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCompleted 결정 제어

TaskCompleted 훅은 작업 완료를 제어하는 두 가지 방법을 지원합니다.

• 종료 코드 2: 작업이 완료로 표시되지 않으며 stderr 메시지가 피드백으로 모델에 전달됩니다.
• JSON {"continue": false, "stopReason": "..."}: 팀원이 턴을 마치면서 이벤트가 트리거된 경우, Stop 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. stopReason은 사용자에게 표시됩니다. TaskUpdate 도구가 이벤트를 트리거한 경우 Claude Code는 continue: false를 무시하며, 종료 코드 2는 여전히 완료를 차단합니다.

이 예시는 테스트를 실행하고 테스트가 실패하면 작업 완료를 차단합니다.

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

메인 Claude Code 에이전트가 응답을 마쳤을 때 실행됩니다. 사용자 중단으로 인해 중지된 경우에는 실행되지 않습니다. API 오류는 대신 StopFailure를 발생시킵니다.

Stop 입력

공통 입력 필드 외에도 Stop 훅은 stop_hook_active, last_assistant_message, background_tasks, session_crons를 전달받습니다. stop_hook_active 필드는 Claude Code가 이미 stop 훅의 결과로 계속 진행 중인 경우 true입니다. 결코 해결되지 않을 조건에서 차단하지 않도록 이 값을 확인하거나 트랜스크립트를 처리합니다. Claude Code는 연속 계속 진행 횟수를 8회로 제한합니다. stop 훅이 턴을 연속으로 8번 계속 진행시킨 후에는 Claude Code가 다음 차단을 재정의하고 턴을 종료합니다. 이 제한을 높이려면 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP을 설정합니다.

last_assistant_message 필드에는 Claude의 최종 응답 텍스트 내용이 포함되므로, 훅은 트랜스크립트 파일을 파싱하지 않고도 이에 접근할 수 있습니다. 소리 내어 읽기 훅이나 알림 훅처럼 방금 완료된 턴에 대해 작동하는 훅의 경우 transcript_path를 읽는 대신 이 필드를 사용합니다. 모든 버전에서 Stop 시점에 트랜스크립트 파일에 최종 메시지가 포함된다고 보장되지 않기 때문입니다.

background_tasks 및 session_crons 배열을 사용하면 훅이 "세션이 완료됨"과 "백그라운드 작업이 세션을 다시 깨울 때까지 일시 중지됨"을 구별할 수 있습니다. 두 배열은 작업 레지스트리에 접근할 수 있을 때 존재하며, 진행 중이거나 예약된 것이 없으면 비어 있습니다.

background_tasks의 각 항목은 진행 중인 작업 하나를 설명하며 다음 필드를 사용합니다.

session_crons의 각 항목은 CronCreate, ScheduleWakeup, /loop에서 가져온 세션 범위의 예약된 깨우기 하나를 설명합니다.

이 예시는 진행 중인 셸 작업 하나와 반복 cron 하나가 있는 Stop 입력을 보여 줍니다.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Stop 결정 제어

Stop 및 SubagentStop 훅은 Claude의 계속 진행 여부를 제어할 수 있습니다. 모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 훅 스크립트는 다음과 같은 이벤트별 필드를 반환할 수 있습니다.

종료 코드 2로 차단하는 훅은 reason과 같은 방식으로 전달됩니다. Claude는 stderr 메시지를 계속 진행해야 하는 이유에 대한 설명으로 전달받습니다.

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

훅이 설계대로 작동하면서 "완료하기 전에 테스트 스위트 실행"과 같은 지침을 Claude에게 제공하는 경우 additionalContext를 사용합니다. 이 필드는 decision: "block"과 같은 루프 보호 장치, 즉 stop_hook_active 입력과 연속 계속 진행 8회 제한을 거쳐 대화를 계속 진행하지만, 트랜스크립트에는 Stop hook feedback으로 표시되고 훅 오류 알림은 표시되지 않습니다.

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

API 오류로 인해 턴이 종료될 때 Stop 대신 실행됩니다. Claude Code는 terminalSequence를 제외한 훅의 출력과 종료 코드를 무시합니다. 속도 제한, 인증 문제 또는 기타 API 오류로 인해 Claude가 응답을 완료할 수 없을 때 실패를 로그에 기록하거나, 알림을 보내거나, 복구 조치를 취하는 데 사용합니다.

StopFailure 입력

공통 입력 필드 외에도 StopFailure 훅은 error, 선택적 error_details, 선택적 last_assistant_message를 전달받습니다. error 필드는 오류 유형을 식별하며 matcher 필터링에 사용됩니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

StopFailure 훅에는 결정 제어가 없습니다. 알림 및 로깅 목적으로만 실행됩니다.

TeammateIdle

에이전트 팀 팀원이 턴을 마친 후 유휴 상태가 되려고 할 때 실행됩니다. 린트 검사 통과를 요구하거나 출력 파일이 존재하는지 확인하는 등, 팀원이 작업을 멈추기 전에 품질 기준을 적용하는 데 사용합니다.

TeammateIdle 훅은 matcher를 지원하지 않으며 매번 발생합니다.

TeammateIdle 입력

공통 입력 필드 외에도 TeammateIdle 훅은 teammate_name과 team_name을 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

TeammateIdle 결정 제어

TeammateIdle 훅은 팀원 동작을 제어하는 두 가지 방법을 지원합니다.

• 종료 코드 2: 팀원이 stderr 메시지를 피드백으로 받고 유휴 상태가 되는 대신 계속 작업합니다.
• JSON {"continue": false, "stopReason": "..."}: Stop 훅 동작과 마찬가지로 팀원을 완전히 중지합니다. stopReason은 사용자에게 표시됩니다.

이 예시는 팀원이 유휴 상태가 되도록 허용하기 전에 빌드 산출물이 존재하는지 확인합니다.

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

세션 중에 설정 파일이 변경될 때 실행됩니다. 설정 변경을 감사하거나, 보안 정책을 적용하거나, 설정 파일에 대한 무단 수정을 차단하는 데 사용합니다.

Claude Code는 설정 파일, 관리형 정책 파일 또는 스킬 파일이 변경될 때 ConfigChange 훅을 실행합니다. 관리형 정책의 경우 managed-settings.json 또는 managed-settings.d/의 파일이 변경될 때만 실행합니다. 서버 관리형 설정과 macOS 관리형 환경설정 또는 Windows 레지스트리 정책의 변경 사항은 훅을 실행하지 않고 적용합니다. wslInheritsWindowsSettings가 적용된 WSL에서는 정책 폴링 시 변경된 Windows 측 관리형 설정 파일도 훅을 실행하지 않고 적용합니다.

matcher는 구성 소스를 기준으로 필터링합니다.

이 예시는 보안 감사를 위해 모든 구성 변경을 로그에 기록합니다.

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

ConfigChange 입력

공통 입력 필드 외에도 ConfigChange 훅은 source와 선택적으로 file_path를 전달받습니다. source 필드는 어떤 구성 유형이 변경되었는지 나타내고, file_path는 수정된 특정 파일의 경로를 제공합니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

ConfigChange 결정 제어

ConfigChange 훅은 구성 변경이 적용되지 않도록 차단할 수 있습니다. 변경을 막으려면 종료 코드 2 또는 JSON decision을 사용합니다. 차단되면 새 설정이 실행 중인 세션에 적용되지 않습니다.

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

policy_settings 변경은 차단할 수 없습니다. 머신의 관리형 설정 파일이 변경되면 policy_settings 소스에 대해서도 훅이 발생하므로 해당 편집을 로그에 기록하는 데 사용할 수 있지만, 차단 결정은 무시됩니다. 이를 통해 엔터프라이즈 관리형 설정이 항상 적용되도록 보장합니다. Claude Code는 서버 관리형 설정이 도착하거나 새로 고쳐질 때 ConfigChange 훅을 실행하지 않습니다.

Claude Code는 ConfigChange 훅의 JSON 출력에서 차단 결정에 따라 동작하며 systemMessage와 continue는 삭제합니다. 차단된 변경은 reason으로 차단하든 종료 코드 2의 stderr로 차단하든 사용자나 Claude에게 아무 메시지도 표시하지 않습니다. Claude Code는 디버그 로그에 한 줄만 기록합니다.

CwdChanged

메인 대화의 셸 명령이 작업 디렉터리를 변경할 때 실행됩니다. 예를 들어 Claude가 cd 명령을 실행하는 경우입니다. 환경 변수 다시 로드, 프로젝트별 도구 체인 활성화, 설정 스크립트 자동 실행 등 디렉터리 변경에 대응하는 데 사용합니다. 디렉터리별 환경을 관리하는 direnv와 같은 도구에는 FileChanged와 함께 사용합니다.

CwdChanged 훅은 CLAUDE_ENV_FILE에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 CwdChanged 이벤트에서 Claude Code가 지울 때까지 이후의 Bash 명령에서 유지됩니다.

CwdChanged는 matcher를 지원하지 않으며 매번 발생합니다.

CwdChanged 입력

공통 입력 필드 외에도 CwdChanged 훅은 old_cwd와 new_cwd를 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

CwdChanged 출력

모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 CwdChanged 훅은 FileChanged가 감시하는 파일 경로를 동적으로 설정하기 위해 watchPaths를 반환할 수 있습니다.

CwdChanged 훅에는 결정 제어가 없습니다. 디렉터리 변경을 차단할 수 없습니다.

Claude Code는 JSON 출력에서 watchPaths와 systemMessage를 읽고 continue는 삭제합니다. 대화형 세션에서는 systemMessage를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 도달하지 않습니다.

DirectoryAdded

세션 중에 사용자가 /add-dir 명령으로 작업 디렉터리를 추가한 후, 또는 SDK 클라이언트가 register_repo_root 제어 요청으로 작업 디렉터리를 추가한 후에 실행됩니다. 예를 들어 의존성을 설치하는 등 새로 추가된 저장소를 준비하는 데 사용합니다.

Claude Code는 다음 경우에 이 이벤트를 발생시키지 않습니다.

• --add-dir 시작 플래그로 디렉터리를 전달하는 경우. 이러한 디렉터리는 SessionStart에서 다룹니다
• /permissions Workspace 탭에서 디렉터리를 추가하는 경우
• 이미 작업 디렉터리이거나 작업 디렉터리 내부에 있는 디렉터리를 추가하는 경우

Claude Code는 샌드박스 및 권한 상태를 새로 고친 후 DirectoryAdded를 발생시키므로, 훅이 실행될 때 샌드박스 처리된 도구는 이미 새 디렉터리를 인식합니다. 훅 명령 자체는 샌드박스 없이 실행됩니다.

Claude Code는 훅을 기다리지 않습니다. 추가는 즉시 완료되며, 훅은 600초 기본 타임아웃으로 백그라운드에서 실행됩니다.

matcher는 디렉터리가 추가된 방식을 기준으로 필터링합니다.

DirectoryAdded 입력

공통 입력 필드 외에도 DirectoryAdded 훅은 directory와 source를 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

DirectoryAdded 훅에는 결정 제어가 없습니다. 훅이 실행될 때 이미 완료된 추가를 차단할 수 없습니다. Claude Code는 JSON 출력에서 continue 필드를 삭제하고 나머지는 소스에 따라 다르게 표시합니다.

• slash_command: Claude Code는 훅의 systemMessage를 사용자에게 표시하는 대신 다음 대화 턴에서 Claude에게 컨텍스트로 전달합니다. 실패한 훅의 개수가 트랜스크립트에 표시됩니다. 전체 실패 출력은 디버그 로그에 기록됩니다
• register_repo_root: Claude Code는 systemMessage 출력과 실패 출력을 디버그 로그에만 기록합니다

FileChanged

감시 중인 파일이 디스크에서 변경될 때 실행됩니다. Claude Code는 도구 호출을 검사하는 것이 아니라 파일 시스템 감시자로 변경을 감지하므로, Edit 또는 Write 도구 호출, Claude가 Bash로 실행하는 스크립트, Claude Code 외부의 프로세스 등 무엇이 파일을 변경했는지와 관계없이 훅을 실행합니다. 일반적인 용도는 프로젝트 설정 파일이 변경될 때 환경 변수를 다시 로드하는 것입니다.

이 이벤트의 matcher는 두 가지 역할을 합니다.

• 감시 목록 구성: 값은 |를 기준으로 분할되며 각 세그먼트는 작업 디렉터리의 리터럴 파일 이름으로 등록되므로, ".envrc|.env"는 정확히 이 두 파일을 감시합니다. 여기서는 정규식 패턴이 유용하지 않습니다. ^\.env와 같은 값은 문자 그대로 ^\.env라는 이름의 파일을 감시합니다.
• 실행할 훅 필터링: 감시 중인 파일이 변경되면 같은 값이 변경된 파일의 basename에 대해 표준 matcher 규칙을 사용하여 실행할 훅 그룹을 필터링합니다.

이 예시는 Bash 명령이나 외부 스크립트가 파일을 다시 쓰는 경우를 포함하여 data.csv가 변경될 때마다 줄 바꿈 문자를 정규화합니다.

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

훅은 stdin의 JSON 입력에 있는 file_path 필드에서 변경된 파일의 절대 경로를 읽습니다. 훅의 grep 가드는 perl이 제거하는 것과 같은 대상, 즉 줄 끝의 CR을 검사하므로 정규화 이후의 실행은 파일을 건드리지 않고 종료됩니다. 가드가 더 느슨하면 무한 루프가 발생합니다. perl -i는 아무것도 치환하지 않더라도 파일을 다시 쓰고, Claude Code는 파일을 다시 쓸 때마다 훅을 다시 실행하기 때문입니다. 이 스크립트를 /path/to/normalize-line-endings.sh에 저장하고 실행 가능하게 만듭니다.

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

훅이 작동하는지 확인하려면 Claude에게 Bash 명령으로 data.csv에 CRLF 줄을 추가하도록 요청합니다. Claude Code가 훅을 실행하면 파일의 줄 바꿈이 LF로 바뀝니다.

미리 이름을 지정할 수 없는 파일을 감시하려면 훅에서 watchPaths를 반환하여 감시 목록을 동적으로 업데이트합니다. Claude Code는 감시할 파일이 지정된 경우에만 감시자를 시작하므로, matcher에 하나 이상의 파일 이름을 지정한 FileChanged 그룹이나 watchPaths를 반환하는 SessionStart 또는 CwdChanged 훅으로 목록을 초기화합니다. 감시 중인 파일이 변경될 때 matcher는 여전히 실행할 훅 그룹을 필터링하므로, 동적 경로를 처리하는 그룹에는 matcher를 생략합니다. matcher를 생략하면 감시 중인 모든 파일과 매칭되며 감시 목록에는 아무것도 추가되지 않습니다. "*" matcher도 모든 파일과 매칭되지만, Claude Code는 이를 다른 값과 마찬가지로 *라는 이름의 리터럴 파일로 감시 목록에 등록합니다.

FileChanged 훅은 CLAUDE_ENV_FILE에 접근할 수 있습니다. 해당 파일에 기록된 변수는 다음 CwdChanged 이벤트에서 Claude Code가 지울 때까지 이후의 Bash 명령에서 유지됩니다.

FileChanged 입력

공통 입력 필드 외에도 FileChanged 훅은 file_path와 event를 전달받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

FileChanged 출력

모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 FileChanged 훅은 감시할 파일 경로를 동적으로 업데이트하기 위해 watchPaths를 반환할 수 있습니다.

FileChanged 훅에는 결정 제어가 없습니다. 파일 변경이 발생하는 것을 차단할 수 없습니다.

Claude Code는 JSON 출력에서 watchPaths와 systemMessage를 읽고 continue는 삭제합니다. 대화형 세션에서는 systemMessage를 짧은 터미널 알림으로 표시합니다. 이 메시지는 SDK 메시지 스트림에 도달하지 않습니다.

WorktreeCreate

claude --worktree, isolation: "worktree"를 사용하는 서브에이전트, 또는 Claude Code가 자체 워크트리에 격리하는 백그라운드 세션 등에서 워크트리가 생성될 때 실행됩니다. 기본적으로 Claude Code는 git worktree로 격리된 작업 사본을 만듭니다. WorktreeCreate 훅을 구성하면 이 기본 git 동작이 대체되므로 SVN, Perforce, Mercurial과 같은 다른 버전 관리 시스템을 사용할 수 있습니다.

훅이 기본 동작을 완전히 대체하므로 .worktreeinclude는 처리되지 않습니다. .env와 같은 로컬 설정 파일을 새 워크트리에 복사해야 한다면 훅 스크립트 내부에서 수행합니다.

훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다. Claude Code는 이 경로를 격리된 세션의 작업 디렉터리로 사용합니다. 각 훅 유형이 경로를 반환하는 방법은 WorktreeCreate 출력을 참조하세요.

Claude Code는 훅의 성공 여부와 반환된 경로에 따라 동작하며, systemMessage와 continue는 삭제합니다.

이 예시는 SVN 작업 사본을 만들고 Claude Code가 사용할 경로를 출력합니다. 저장소 URL을 자신의 것으로 바꾸세요.

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

훅은 stdin의 JSON 입력에서 worktree name을 읽고, 새 디렉터리에 새 사본을 체크아웃한 다음, 디렉터리 경로를 출력합니다. 마지막 줄의 echo가 Claude Code가 worktree 경로로 읽는 부분입니다. 경로에 간섭하지 않도록 다른 모든 출력은 stderr로 리디렉션합니다.

WorktreeCreate 입력

공통 입력 필드 외에도 WorktreeCreate 훅은 name 필드를 전달받습니다. 이는 새 워크트리의 슬러그 식별자로, 사용자가 지정하거나 자동 생성되며 예를 들면 bold-oak-a3f2와 같습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

WorktreeCreate 출력

WorktreeCreate 훅은 표준 허용/차단 결정 모델을 사용하지 않습니다. 대신 훅의 성공 또는 실패가 결과를 결정합니다. 훅은 생성된 worktree 디렉터리의 경로를 반환해야 합니다.

• 명령 훅 (type: "command"): 경로를 stdout의 마지막 비어 있지 않은 줄로 출력합니다. Claude Code는 해당 줄을 읽기 전에 ANSI 이스케이프 코드를 제거하므로 echo 전에 출력된 셸 시작 배너는 무시됩니다. 그 밖의 훅 출력은 stderr로 리디렉션합니다.
• HTTP 훅 (type: "http"): 응답 본문에 { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }를 반환합니다.

훅이 실패하거나 경로를 생성하지 않으면 worktree 생성이 오류와 함께 실패합니다.

Claude Code는 상대 경로를 훅이 실행된 디렉터리를 기준으로 해석하며, 경로에 포함된 . 또는 .. 세그먼트를 정리합니다. 결과 경로가 Claude Code가 진입할 수 있는 디렉터리가 아니면 세션은 해당 경로를 명시한 오류를 출력하고 코드 1로 종료합니다.

Claude Code는 . 또는 .. 세그먼트를 포함하는 절대 경로와 저장소 루트 아래의 심볼릭 링크를 통과하는 모든 경로를 거부합니다. 저장소에 커밋된 심볼릭 링크가 worktree를 저장소 외부로 리디렉션할 수 있기 때문입니다. 오류에는 거부된 구성 요소가 명시됩니다. 저장소 내부의 심볼릭 링크를 통과하지 않는 정규화된 경로를 반환해야 합니다. v2.1.216 이전에는 worktree 생성 시 이러한 검사 없이 훅의 경로를 그대로 따랐습니다.

WorktreeRemove

worktree가 제거될 때 실행됩니다. WorktreeCreate에 대응하는 정리용 이벤트입니다. 이 이벤트는 다음과 같은 경우에 발생합니다.

• --worktree 세션을 종료하면서 제거를 선택한 경우
• isolation: "worktree"가 설정된 서브에이전트가 완료된 경우
• 훅이 생성한 worktree를 사용하는 백그라운드 세션을 삭제한 경우

git 기반 worktree의 경우 Claude Code가 git worktree remove로 정리를 자동 처리합니다. WorktreeCreate 훅을 구성했다면 WorktreeRemove 훅과 함께 사용하여 해당 훅이 생성한 worktree의 정리를 제어하십시오.

• WorktreeRemove 훅이 없는 경우: --worktree 세션을 종료하면서 제거를 선택하면 Claude Code는 WorktreeCreate 훅이 반환한 경로에 대해 git worktree remove --force로 폴백하므로, git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 worktree(예: 훅이 git 이외의 버전 관리 시스템으로 생성한 worktree)는 디스크에 남습니다. 백그라운드 세션을 삭제할 때 훅이 생성한 worktree가 어떻게 처리되는지는 에이전트 뷰의 삭제 규칙을 참조하십시오.
• 훅이 0으로 종료하는 경우: worktree가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 정보를 읽지 않으므로 훅이 디렉터리를 실제로 삭제했는지 확인해야 합니다.
• 훅이 0이 아닌 코드로 종료하는 경우: 이후에도 worktree_path의 디렉터리가 존재하면 제거가 실패하며, worktree는 git 폴백 없이 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 WorktreeRemove 입력을 참조하십시오.

Claude Code는 WorktreeCreate 훅이 반환한 경로만 알기 때문에 훅이 생성한 worktree에 속한 브랜치를 삭제하지 않습니다. WorktreeCreate 훅이 브랜치를 생성한다면 WorktreeRemove 훅에서 해당 브랜치를 삭제하십시오.

Claude Code는 WorktreeRemove 훅의 systemMessage, continue 등 JSON 출력 필드를 무시합니다.

백그라운드 세션 삭제 시 Claude Code는 훅을 실행하기 전에 저장된 worktree 경로를 검증하며, 심볼릭 링크이거나 저장소 루트 아래의 심볼릭 링크를 통과하는 경로는 거부합니다. 아직 파일이 남아 있는 worktree에 대해서는 에이전트 뷰에서 삭제를 확인한 경우에만 훅이 실행됩니다. 이러한 worktree의 경우 claude rm은 세션과 worktree를 그대로 유지합니다. v2.1.216 이전에는 이러한 검사 없이 저장된 경로에 대해 훅이 실행되었습니다.

Claude Code는 WorktreeCreate가 반환한 경로를 훅 입력의 worktree_path로 전달합니다. 다음 예시는 해당 경로를 읽어 디렉터리를 제거합니다.

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

WorktreeRemove 입력

공통 입력 필드 외에도 WorktreeRemove 훅은 제거되는 worktree의 절대 경로인 worktree_path 필드를 받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

WorktreeRemove 훅의 종료 코드가 결과를 결정합니다. 훅이 0이 아닌 코드로 종료하고 이후에도 worktree_path의 디렉터리가 존재하면 제거가 실패합니다.

• worktree는 디스크에 남으며, 훅의 명령과 stderr는 디버그 로그에 기록됩니다.
• 백그라운드 세션을 삭제하던 중이었다면 세션도 유지됩니다. 에이전트 뷰의 거부 메시지는 exited 1과 같이 훅이 어떻게 종료되었는지 보고하고, stderr의 앞부분을 인용하며, 세션을 다시 삭제하면 디렉터리가 어쨌든 제거되는지 여부를 알려 줍니다.

PreCompact

Claude Code가 압축 작업을 실행하기 직전에 실행됩니다.

matcher 값은 압축이 수동으로 트리거되었는지 자동으로 트리거되었는지를 나타냅니다.

압축을 차단하려면 코드 2로 종료합니다. 수동 /compact의 경우 stderr 메시지가 사용자에게 표시됩니다. "decision": "block"이 포함된 JSON을 반환하여 차단할 수도 있습니다.

자동 압축을 차단하면 발생 시점에 따라 효과가 다릅니다. 컨텍스트 한도에 도달하기 전에 선제적으로 압축이 트리거된 경우 Claude Code는 압축을 건너뛰고 압축되지 않은 상태로 대화를 계속합니다. API가 이미 반환한 컨텍스트 한도 오류에서 복구하기 위해 압축이 트리거된 경우에는 원래 오류가 표시되고 현재 요청이 실패합니다.

Claude Code는 PreCompact 훅의 systemMessage 및 continue 필드를 무시합니다.

PreCompact 입력

공통 입력 필드 외에도 PreCompact 훅은 trigger와 custom_instructions를 받습니다. manual의 경우 custom_instructions에는 사용자가 /compact에 전달한 내용이 담기며, 아무것도 전달하지 않으면 null입니다. auto의 경우 custom_instructions는 null입니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": null
}

PostCompact

Claude Code가 압축 작업을 완료한 후 실행됩니다. 이 이벤트를 사용하여 새로 압축된 상태에 대응할 수 있습니다. 예를 들어 생성된 요약을 로그에 기록하거나 외부 상태를 업데이트할 수 있습니다. Claude Code는 PostCompact 훅의 systemMessage 및 continue 필드를 무시합니다.

PreCompact와 동일한 matcher 값이 적용됩니다.

PostCompact 입력

공통 입력 필드 외에도 PostCompact 훅은 trigger와 compact_summary를 받습니다. compact_summary 필드에는 압축 작업으로 생성된 대화 요약이 담깁니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

PostCompact 훅에는 결정 제어 기능이 없습니다. 압축 결과에 영향을 줄 수는 없지만 후속 작업을 수행할 수 있습니다.

PreModelSwitch

사용자 또는 클라이언트가 요청한 모델 전환을 Claude Code가 적용하기 전에 실행됩니다. 전환을 차단하거나, 확인을 요구하거나, 전환이 일어나기 전에 전환 비용을 보여 주는 데 사용합니다.

PreModelSwitch에는 Claude Code v2.1.251 이상이 필요합니다. Claude Code는 다음 요청에 대해 이 훅을 실행합니다.

• /model <name> 및 /model 선택기
• Option+P 또는 Alt+P 모델 선택기
• /config의 Model 설정
• 세션의 모델을 변경하는 빠른 모드 켜기
• Agent SDK 호스트 또는 Remote Control의 set_model 요청, 또는 apply_flag_settings 요청에 포함된 모델 변경

Claude Code는 자동 모델 폴백이나 세션 재개 시 모델 복원처럼 자체적으로 수행하는 전환에 대해서는 PreModelSwitch 훅을 실행하지 않습니다. 이러한 변경은 PostModelSwitch에만 전달됩니다.

Claude Code는 [1m] 접미사를 무시하고, 세션이 전환하려는 모델의 정식 이름과 matcher를 비교합니다. opus와 같은 별칭, 날짜가 포함된 모델 ID, Amazon Bedrock 모델 ID와 같은 제공업체별 ID는 모두 해석 결과인 하나의 정식 이름과 일치하므로, claude-opus-5는 Opus 5의 모든 표기를 포괄합니다.

LLM 게이트웨이만 아는 사용자 지정 모델 ID처럼 Claude Code가 대상의 정식 이름을 확인할 수 없는 경우에는 matcher와 관계없이 모든 PreModelSwitch 훅을 실행합니다. 따라서 차단하는 훅은 matcher에만 의존하지 말고 입력의 to_model을 확인해야 합니다.

matcher는 정확한 이름, claude-opus-4-6|claude-opus-5와 같은 |로 구분된 목록, 또는 .*opus.*와 같은 정규식으로 작성합니다. 다음 예시는 정확한 이름 matcher를 사용하면서 훅 입력의 to_model도 확인하므로, 코드 2로 종료하여 Opus 4.6으로의 전환을 거부하고 다른 대상은 허용합니다.

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 /model claude-opus-4-6을 실행합니다. Claude Code는 현재 모델을 유지하고, PreModelSwitch 훅이 전환을 차단했다고 보고하며, 작성한 메시지를 이유로 표시합니다.

PreModelSwitch 입력

공통 입력 필드 외에도 PreModelSwitch 훅은 다음 표의 필드를 받습니다. 마지막 다섯 개 필드는 대화를 새 모델로 다시 전송하는 비용을 설명하므로, 훅은 전환이 일어나기 전에 해당 수치를 보여 줄 수 있습니다.

다음 예시는 Sonnet 5를 실행 중인 세션에서 /model opus를 실행할 때의 입력을 보여 줍니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

PreModelSwitch 결정 제어

PreModelSwitch 훅은 전환을 취소하거나, 사용자에게 확인을 요청하거나, 전환을 진행하도록 할 수 있습니다. 종료 코드 2 또는 최상위 수준의 decision: "block"은 전환을 취소합니다.

보다 세밀하게 제어하려면 PreToolUse와 마찬가지로 hookSpecificOutput 객체에 permissionDecision과 permissionDecisionReason을 반환합니다. PreModelSwitch는 "allow", "deny", "ask"를 허용합니다. "defer", updatedInput, additionalContext는 허용하지 않습니다. 아래 표에서 두 필드를 설명합니다.

대화형 세션의 /model만 "ask" 프롬프트를 표시할 수 있습니다. -p 플래그를 사용하는 비대화형 모드, /config, set_model 요청을 포함한 다른 모든 사용 환경에서는 Claude Code가 "ask"를 거부로 처리합니다.

다음 예시는 사용자에게 확인을 요청하며 context_tokens의 토큰 수를 인용합니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

여러 PreModelSwitch 훅이 서로 다른 결정을 반환하면 우선순위는 deny > ask > allow입니다.

Claude Code는 결정과 관계없이 훅이 반환한 systemMessage를 사용자에게 표시하므로, 비용 보고 훅은 {"systemMessage": "..."}를 반환하고 0으로 종료할 수 있습니다.

타임아웃 전에 응답하지 않는 PreModelSwitch 훅은 전환을 차단합니다. 반면 PreToolUse에서는 시간 초과된 명령 훅이 도구 호출을 계속 진행하도록 합니다. 이 이벤트의 기본 타임아웃은 30초입니다. PreModelSwitch는 command, http, mcp_tool 훅만 실행하므로 prompt 및 agent 기본값은 적용되지 않습니다.

0 또는 2 이외의 코드로 종료하고 JSON 결정을 출력하지 않는 훅은 차단하지 않습니다. 기타 종료 코드에 설명된 대로 Claude Code는 해당 stderr를 표시하고 전환을 적용합니다.

PostModelSwitch

세션의 모델이 변경된 후 실행됩니다. 모든 CLAUDE.md를 편집하지 않고도 Claude에게 모델별 지침을 제공하는 데 사용합니다. 예를 들어 특정 모델에 적용되는 조직 전체 지침을 제공할 수 있습니다.

PostModelSwitch에는 Claude Code v2.1.251 이상이 필요합니다. 모델이 이미 변경된 후이므로 차단할 수 없습니다. Claude Code는 다음 변경 후에 PostModelSwitch 훅을 실행합니다.

• 사용자 또는 클라이언트가 요청한 전환
• 세션의 모델을 변경하는 자동 모델 폴백
• opusplan과 같은 설정에서 플랜 모드에 진입하거나 플랜 모드를 벗어나는 경우
• 세션 재개 시 Claude Code가 모델을 복원하는 경우

폴백 모델 체인의 모델이 턴을 처리하는 경우에는 Claude Code가 PostModelSwitch 훅을 실행하지 않습니다. 해당 대체는 한 턴 동안만 지속되며 세션의 모델을 변경하지 않기 때문입니다.

matcher는 PreModelSwitch와 동일한 규칙을 따릅니다. Claude Code는 세션이 전환된 모델의 정식 이름과 matcher를 비교합니다.

다음 예시는 세션의 모델이 Opus 모델로 변경될 때마다 지침을 추가합니다.

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

훅이 작동하는지 확인하려면 다른 모델을 실행 중인 세션에서 Opus 모델로 전환한 다음(예: Sonnet 세션에서 /model opus 실행), 현재 모델에 대해 어떤 지침을 가지고 있는지 Claude에게 물어보십시오.

PostModelSwitch 입력

PostModelSwitch 훅은 PreModelSwitch와 동일한 필드를 받으며, hook_event_name은 "PostModelSwitch"로 설정되고 source 값이 두 가지 추가됩니다. 자동 폴백 또는 Claude Code가 자체적으로 수행한 기타 변경의 경우 "auto", 세션 재개 시 복원된 모델의 경우 "resume"입니다.

source가 "auto"이면 requested_model은 null입니다. source가 "resume"이면 Claude Code가 복원한 저장된 모델 설정입니다.

PostModelSwitch 결정 제어

Claude Code는 종료 코드 0일 때 훅의 일반 텍스트 stdout 또는 JSON 출력의 additionalContext를 가져와, 전환 후 다음 요청과 함께 Claude에게 전달합니다. 모든 훅에서 사용할 수 있는 JSON 출력 필드 외에도 다음을 반환할 수 있습니다.

다음 프롬프트를 보낸 후 5초 이내에 훅이 완료되지 않으면 Claude Code는 출력 없이 해당 요청을 보내고 대신 그다음 요청에 출력을 첨부합니다. 다음 요청 전에 모델이 여러 번 변경되면 Claude Code는 마지막 전환의 대상 모델에 대한 출력만 전달합니다.

SessionEnd

Claude Code 세션이 종료될 때 실행됩니다. 정리 작업, 세션 통계 로깅 또는 세션 상태 저장에 유용합니다. 종료 이유로 필터링하는 matcher를 지원합니다.

훅 입력의 reason 필드는 세션이 종료된 이유를 나타냅니다.

SessionEnd 입력

공통 입력 필드 외에도 SessionEnd 훅은 세션이 종료된 이유를 나타내는 reason 필드를 받습니다. 모든 값은 위의 이유 표를 참조하십시오.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

SessionEnd 훅에는 결정 제어 기능이 없습니다. 세션 종료를 차단할 수는 없지만 정리 작업을 수행할 수 있습니다. Claude Code는 systemMessage 등 해당 훅의 JSON 출력 필드를 무시합니다.

SessionEnd 훅의 기본 타임아웃은 1.5초입니다. 이 타임아웃은 종료할 때, /clear를 실행할 때, 또는 대화형 /resume으로 세션을 전환할 때 적용됩니다. 훅에 더 많은 시간을 주는 방법은 두 가지입니다.

• 훅별 timeout: 해당 훅의 구성에서 timeout을 설정합니다. 전체 허용 시간은 설정 파일에 있는 가장 높은 훅별 timeout에 맞춰 최대 60초까지 자동으로 늘어납니다. 이 방식으로 허용 시간을 늘려도 자체 timeout이 없는 훅은 여전히 기본값을 유지합니다. 플러그인이 제공하는 훅에 설정된 타임아웃은 허용 시간을 늘리지 않습니다.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS: 이 환경 변수를 밀리초 단위로 설정하여 허용 시간을 명시적으로 재정의합니다. 설정한 값은 자체 timeout이 없는 각 훅의 타임아웃으로도 사용됩니다.

다음 예시는 허용 시간을 5초로 설정합니다.

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

v2.1.268 이전에는 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS가 전체 허용 시간만 늘렸으며, 자체 timeout이 없는 훅은 여전히 1.5초 후에 취소되었습니다.

Elicitation

MCP 서버가 작업 도중 사용자 입력을 요청할 때 실행됩니다. 기본적으로 Claude Code는 사용자가 응답할 수 있도록 대화형 대화 상자를 표시합니다. 훅은 이 요청을 가로채 프로그래밍 방식으로 응답하여 대화 상자를 완전히 건너뛸 수 있습니다.

matcher 필드는 MCP 서버 이름과 비교됩니다.

Elicitation 입력

공통 입력 필드 외에도 Elicitation 훅은 mcp_server_name, message 및 선택적 필드인 mode, url, elicitation_id, requested_schema를 받습니다.

가장 일반적인 경우인 폼 모드 elicitation의 예시입니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

브라우저 기반 인증에 사용되는 URL 모드 elicitation의 예시입니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Elicitation 출력

대화 상자를 표시하지 않고 프로그래밍 방식으로 응답하려면 hookSpecificOutput이 포함된 JSON 객체를 반환합니다.

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

종료 코드 2는 elicitation을 거부합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.

Claude Code는 Elicitation 훅의 JSON 출력에서 hookSpecificOutput에 따라 동작하며 systemMessage와 continue는 무시합니다.

ElicitationResult

사용자가 MCP elicitation에 응답한 후 실행됩니다. 훅은 응답이 MCP 서버로 다시 전송되기 전에 이를 관찰, 수정 또는 차단할 수 있습니다.

matcher 필드는 MCP 서버 이름과 비교됩니다.

ElicitationResult 입력

공통 입력 필드 외에도 ElicitationResult 훅은 mcp_server_name, action 및 선택적 필드인 mode, elicitation_id, content를 받습니다.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

ElicitationResult 출력

사용자의 응답을 재정의하려면 hookSpecificOutput이 포함된 JSON 객체를 반환합니다.

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

종료 코드 2는 응답을 차단하여 실제 적용되는 작업을 decline으로 변경합니다. Claude Code는 stderr 메시지를 어디에도 표시하지 않습니다.

Claude Code는 ElicitationResult 훅의 JSON 출력에서 hookSpecificOutput에 따라 동작하며 systemMessage와 continue는 무시합니다.

프롬프트 기반 hook

명령, HTTP 및 MCP tool hook 외에도 Claude Code는 LLM을 사용하여 작업을 허용할지 차단할지 평가하는 프롬프트 기반 hook (type: "prompt")과 도구 액세스가 있는 에이전트 검증자를 생성하는 에이전트 hook (type: "agent")을 지원합니다. 모든 이벤트가 모든 hook 유형을 지원하는 것은 아닙니다.

다섯 가지 hook 유형 모두 (command, http, mcp_tool, prompt, agent)를 지원하는 이벤트:

• PermissionDenied
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest는 command, http, mcp_tool, prompt 훅을 지원하지만 agent 훅은 지원하지 않습니다. 이 이벤트에 에이전트 훅을 구성하면 Claude Code는 이를 건너뛰고 권한 흐름은 변경 없이 진행됩니다. 훅에서 허용하거나 거부하려면 명령 또는 HTTP 훅에서 결정 객체를 반환합니다.

command, http 및 mcp_tool hook을 지원하지만 prompt 또는 agent는 지원하지 않는 이벤트:

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart 및 Setup은 command 및 mcp_tool hook을 지원하며, MCP tool hook 필드는 해당 mcp_tool hook이 실행되는 시기를 설명합니다. http, prompt 또는 agent hook은 지원하지 않습니다.

프롬프트 기반 hook이 어떻게 작동하는지

프롬프트 기반 hook은 Bash 명령을 실행하는 대신:

1. 훅 입력과 프롬프트를 Claude 모델로 전송합니다. 기본값은 Claude Code가 백그라운드 기능에 사용하는 모델입니다
2. LLM은 결정을 포함하는 구조화된 JSON으로 응답합니다
3. Claude Code는 결정을 자동으로 처리합니다

프롬프트 hook 구성

type을 "prompt"로 설정하고 command 대신 prompt 문자열을 제공합니다. $ARGUMENTS 자리 표시자를 사용하여 hook의 JSON 입력 데이터를 프롬프트 텍스트에 주입합니다.

이 Stop hook은 Claude가 완료되기 전에 모든 작업이 완료되었는지 평가하도록 LLM에 요청합니다:

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

응답 스키마

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

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

ok: false에서 발생하는 상황은 이벤트에 따라 다릅니다:

• Stop 및 SubagentStop: 이유는 Claude의 다음 명령으로 피드백되며 턴이 계속됩니다. 응답이 impossible: true도 설정하지 않는 한, 이 경우 Claude Code는 중지를 허용하고 턴이 종료됩니다
• PreToolUse: tool 호출이 거부됩니다. 기본적으로 턴이 끝나고 거부 이유가 채팅에 경고 줄로 나타납니다. continueOnBlock: true를 설정하여 이유를 Claude에 tool 오류로 반환하여 조정하고 계속할 수 있도록 합니다. 이는 명령 hook의 permissionDecision: "deny"와 동일합니다. v2.1.210 이전에는 거부 이유가 Claude에 tool 오류로 반환되었고 턴이 계속되었습니다
• PostToolUse: 기본적으로 턴이 끝나고 이유는 채팅에 경고 줄로 나타납니다. 대신 continueOnBlock: true를 설정하여 이유를 Claude에 다시 피드백하고 턴을 계속합니다
• PostToolBatch, UserPromptSubmit 및 UserPromptExpansion: 턴이 끝나고 이유는 경고 줄로 나타납니다. 이러한 이벤트는 continue에 관계없이 decision: "block"에서 턴을 종료합니다
• PostToolUseFailure 및 TaskCreated: 이유는 Claude에 tool 오류로 반환되며 턴이 계속됩니다. continueOnBlock에 관계없이
• TaskCompleted: 턴 중에 작업이 완료됨으로 표시되어 발생할 때 이유는 Claude에 tool 오류로 반환되며 턴이 계속됩니다. continueOnBlock에 관계없이. 팀원이 중지되어 발생할 때 TeammateIdle처럼 동작하며 기본적으로 팀원을 중지합니다
• TeammateIdle: 기본적으로 팀원이 중지되고 이유는 경고 줄로 나타납니다. continueOnBlock: true를 설정하여 이유를 팀원에게 다시 피드백하고 계속 작업하도록 유지합니다
• PermissionRequest: ok: false는 효과가 없습니다. hook에서 승인을 거부하려면 hookSpecificOutput.decision.behavior: "deny"를 반환하는 명령 hook을 사용합니다
• PermissionDenied: ok: false는 거부가 이미 발생했기 때문에 효과가 없습니다. 이 이벤트가 읽는 유일한 출력은 hookSpecificOutput.retry이며, 프롬프트 및 에이전트 hook은 이를 설정할 수 없습니다. 이들은 이 이벤트에서 실행되지만 출력은 버려집니다. retry를 반환하려면 명령 hook을 사용합니다

이벤트에 대해 더 세밀한 제어가 필요한 경우 결정 제어에 설명된 이벤트별 필드가 있는 명령 hook을 사용합니다.

중지하기 전에 여러 조건 확인

이 Stop hook은 Claude가 중지하기 전에 세 가지 조건을 확인하는 자세한 프롬프트를 사용합니다. SubagentStop hook은 subagent가 중지해야 하는지 평가하는 동일한 형식을 사용합니다. 모델이 조건이 아직 충족되지 않았기 때문에 "ok": false를 반환하면 Claude는 제공된 이유를 다음 명령으로 받으며 계속 작업합니다:

{
  "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
          }
        ]
      }
    ]
  }
}

에이전트 기반 hook

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

에이전트 hook이 어떻게 작동하는지

에이전트 hook이 발생할 때:

1. Claude Code는 프롬프트와 hook의 JSON 입력을 가진 subagent를 생성합니다
2. subagent는 Read, Grep, Glob과 같은 도구를 사용하여 조사할 수 있습니다
3. 최대 50턴 후 subagent는 구조화된 { "ok": true/false } 결정을 반환합니다
4. Claude Code는 ok가 true이면 작업을 허용합니다. ok가 false이면 Claude Code는 응답 스키마에 나열된 해당 이벤트에서 continueOnBlock: true를 사용하는 프롬프트 hook과 동일한 방식으로 블록을 처리합니다

에이전트 hook은 검증이 hook 입력 데이터만으로 평가하는 것이 아니라 실제 파일이나 테스트 출력을 검사해야 할 때 유용합니다.

에이전트 hook 구성

type을 "agent"로 설정하고 hook 입력 JSON에 대한 자리 표시자로 $ARGUMENTS를 사용하여 prompt 문자열을 제공합니다. 구성 필드는 프롬프트 hook과 동일하지만 에이전트 hook은 60초의 더 긴 기본 시간 초과를 가지며 continueOnBlock 필드가 없습니다.

응답 스키마는 허용하려면 { "ok": true }이거나 차단하려면 { "ok": false, "reason": "..." }입니다. ok: false일 때 Claude Code는 동일한 이벤트에서 continueOnBlock: true를 사용하는 프롬프트 hook을 처리하는 방식으로 에이전트 hook을 처리합니다. 에이전트 hook은 continueOnBlock 필드가 없으며 프롬프트 hook의 impossible 필드를 지원하지 않습니다.

이 Stop hook은 Claude가 완료되기 전에 모든 단위 테스트가 통과하는지 확인합니다:

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

백그라운드에서 hook 실행

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

비동기 hook 구성

hook 구성에 "async": true를 추가하여 Claude를 차단하지 않고 백그라운드에서 실행합니다. 이 필드는 type: "command" hook에서만 사용 가능합니다.

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

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

비동기 hook이 백그라운드에서 실행되면 Claude Code는 timeout을 적용하지 않습니다. Claude Code는 여전히 asyncRewake로 실행하는 hook에 timeout을 적용합니다.

Claude Code는 비동기 hook의 결과를 세션이 실행되는 동안에만 전달합니다:

• -p 플래그가 있는 비대화형 모드에서 Claude Code는 종료 시 여전히 실행 중인 비동기 hook을 종료하고 결과를 cancelled로 완료합니다
• hook의 작업이 claude -p 세션을 초과해야 하는 경우 완전히 분리된 프로세스를 시작합니다

비동기 hook이 어떻게 실행되는지

비동기 hook이 발생하면 Claude Code는 hook 프로세스를 시작하고 완료를 기다리지 않고 즉시 계속합니다. hook은 동기 hook과 동일한 JSON 입력을 stdin을 통해 받습니다.

백그라운드 프로세스가 종료된 후 Claude Code는 hook의 JSON 응답에서 additionalContext 및 systemMessage 필드를 다음 대화 턴에서 Claude에 전달합니다. 동기 hook의 systemMessage와 달리 두 필드 모두 사용자에게 표시되지 않습니다.

Claude Code는 JSON 응답을 동기 hook과 동일한 출력 스키마에 대해 검증하고, systemMessage가 문자열이 아닌 경우와 같이 값의 유형이 잘못된 필드를 전달하지 않고 삭제합니다. --debug로 실행하여 삭제된 각 필드의 이름을 지정하는 경고를 확인합니다. v2.1.202 이전에는 비동기 hook의 잘못된 형식의 JSON 출력이 세션을 충돌시킬 수 있었고, 세션이 재개될 때마다 충돌이 반복되었습니다.

비동기 hook 완료 알림은 기본적으로 억제됩니다. 보려면 Ctrl+O로 자세한 모드를 활성화하거나 --verbose로 Claude Code를 시작합니다.

파일 변경 후 테스트 실행

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

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

# stdin에서 hook 입력을 읽습니다
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 소스 파일에 대해서만 테스트를 실행합니다
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# 테스트를 실행하고 additionalContext를 통해 결과를 Claude에 보고합니다
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

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

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

제한 사항

비동기 hook은 동기 hook과 비교하여 여러 제약이 있습니다:

• Hook 출력은 다음 대화 턴에 전달됩니다. 세션이 유휴 상태이면 응답은 다음 사용자 상호 작용까지 기다립니다. 예외: asyncRewake hook이 종료 코드 2로 종료되면 세션이 유휴 상태일 때도 Claude를 즉시 깨웁니다.
• 각 실행은 별도의 백그라운드 프로세스를 생성합니다. 동일한 비동기 hook의 여러 발생에 걸쳐 중복 제거가 없습니다.

보안 고려 사항

면책 조항

작업 공간 신뢰

Claude Code는 설정 파일에서 hook을 실행하기 전에 작업 공간 신뢰를 확인합니다. 신뢰할 수 있는 것으로 간주되는 것은 세션 유형에 따라 다릅니다:

• 대화형 세션: Claude Code는 사용자의 ~/.claude/settings.json을 포함한 모든 설정 파일의 hook을 보류하며, 폴더에 대한 작업 공간 신뢰 대화를 수락하거나 신뢰가 확장되는 상위 디렉토리에 대해 수락할 때까지 보류합니다
• -p 또는 SDK 세션: Claude Code는 대화를 표시하지 않으며 폴더를 신뢰할 수 있는 것으로 취급하므로, 리포지토리의 .claude/settings.json에 커밋된 hook은 신뢰한 적이 없는 폴더에서 실행됩니다

작성하지 않은 리포지토리에 대해 claude -p를 스크립팅하기 전에 해당 .claude/ 설정 파일을 검토하고, --bare로 시작하거나, --settings '{"disableAllHooks": true}'를 사용하여 해당 실행에 대해 hook을 비활성화하세요. 프로젝트 서브에이전트의 frontmatter hook은 설정 파일 hook보다 더 엄격한 규칙을 따릅니다. 폴더를 신뢰하기 전에 실행되는 것은 세션 유형별로 각 종류의 리포지토리 콘텐츠를 나열합니다.

보안 모범 사례

hook을 작성할 때 이러한 사례를 염두에 두세요:

• 입력 검증 및 살균: 입력 데이터를 맹목적으로 신뢰하지 마세요
• 항상 셸 변수를 따옴표로 감싸세요: $VAR 대신 "$VAR" 사용
• 경로 순회 차단: 파일 경로에서 .. 확인
• 절대 경로 사용: 스크립트의 전체 경로를 지정하세요. exec 형식에서는 ${CLAUDE_PROJECT_DIR}을 사용하고 경로는 따옴표가 필요하지 않습니다. shell 형식에서는 큰따옴표로 감싸세요
• 민감한 파일 건너뛰기: .env, .git/, 키 등을 피하세요

Windows PowerShell 도구

Windows에서 명령 hook에 "shell": "powershell"을 설정하여 PowerShell에서 개별 hook을 실행할 수 있습니다. Claude Code는 PowerShell 7 이상의 실행 파일인 pwsh.exe를 자동 감지하고 Windows PowerShell 5.1의 powershell.exe로 폴백합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

PowerShell 셸 형식 명령에서 프로젝트 루트를 참조하려면 ${CLAUDE_PROJECT_DIR} 또는 $env:CLAUDE_PROJECT_DIR을 작성합니다. Claude Code는 훅이 settings.json, 플러그인 또는 스킬에 정의되어 있는지 여부와 관계없이 PowerShell 셸 형식 명령에서 ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} 및 ${CLAUDE_PLUGIN_DATA} 자리 표시자를 PowerShell의 ${env:NAME} 형식으로 다시 작성합니다. PowerShell은 구문 분석 후 내보낸 환경에서 값을 확인하므로 자리 표시자는 큰따옴표로 묶인 문자열 내에서는 작동하지만 PowerShell이 변수를 확장하지 않는 작은따옴표로 묶인 문자열 내에서는 작동하지 않습니다.

PowerShell hook에서 $CLAUDE_PROJECT_DIR의 단순한 형식을 작성하지 마십시오. PowerShell은 이를 정의되지 않은 로컬 변수로 구문 분석하고 $null로 확인하므로 스크립트 경로가 프로젝트 루트 접두사 없이 남습니다. Claude Code는 해당 형식을 다시 작성하지 않으며 대신 디버그 로그에 경고를 기록합니다.

아래 예제는 $env: 형식으로 프로젝트 스크립트를 실행하는 settings.json 훅을 보여줍니다:

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

Hook 디버그

Hook 실행 세부 정보는 디버그 로그 파일에 기록됩니다. claude --debug-file <path>로 Claude Code를 시작하여 로그를 알려진 위치에 작성하거나 claude --debug를 실행하고 ~/.claude/debug/<session-id>.txt에서 로그를 읽습니다. --debug 플래그는 터미널에 인쇄하지 않습니다.

예를 들어, Write에서 hook-ran을 인쇄하는 명령을 가진 PostToolUse hook은 다음과 같은 항목을 생성합니다:

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

더 세밀한 hook 일치 세부 정보를 보려면 CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose를 설정하여 hook matcher 수 및 쿼리 일치와 같은 추가 로그 줄을 확인합니다.

hook이 발생하지 않음, 무한 Stop hook 루프 또는 구성 오류와 같은 일반적인 문제 해결은 가이드의 제한 사항 및 문제 해결을 참조하세요. /context, /doctor 및 설정 우선순위를 다루는 더 광범위한 진단 안내는 구성 디버그를 참조하세요.