Dalam mode non-interaktif dengan flag -p, Claude Code menawarkan AskUserQuestion dan ExitPlanMode hanya ketika run memiliki permission host untuk menerima prompt, seperti callback canUseTool Agent SDK. Tools ini memerlukan interaksi pengguna. Mengembalikan permissionDecision: "allow" bersama dengan updatedInput memenuhi persyaratan itu: hook membaca input tool dari stdin, mengumpulkan jawaban melalui UI Anda sendiri, dan mengembalikannya dalam updatedInput sehingga tool dijalankan tanpa meminta. Mengembalikan "allow" saja tidak cukup untuk tools ini. Untuk AskUserQuestion, kembalikan array questions asli dan tambahkan objek answers yang memetakan teks setiap pertanyaan ke jawaban yang dipilih.

Mulai dari v2.1.199, tool MCP yang server-nya menandainya dengan _meta["anthropic/requiresUserInteraction"] lebih ketat: hook tidak dapat melewati prompt persetujuannya dengan "allow", dengan atau tanpa updatedInput, karena Claude Code tidak dapat mengkonfirmasi hook mengumpulkan interaksi yang dibutuhkan tool.

Defer a tool call for later

"defer" adalah untuk integrasi yang menjalankan claude -p sebagai subprocess dan membaca output JSON-nya, seperti aplikasi Agent SDK atau UI kustom yang dibangun di atas Claude Code. Ini memungkinkan proses pemanggil itu menjeda Claude pada pemanggilan tool, mengumpulkan input melalui antarmuka miliknya sendiri, dan melanjutkan di mana ia berhenti. Claude Code menghormati nilai ini hanya dalam mode non-interaktif dengan flag -p. Dalam sesi interaktif itu mencatat peringatan dan mengabaikan hasil hook.

Tool AskUserQuestion adalah kasus tipikal: Claude ingin menanyakan sesuatu kepada pengguna, tetapi tidak ada terminal untuk menjawab. Run -p menawarkan AskUserQuestion hanya ketika memiliki permission host, seperti tool MCP yang Anda berikan dengan --permission-prompt-tool, jadi mulai run dengan salah satunya. Perjalanan bolak-balik bekerja seperti ini:

1. Claude memanggil AskUserQuestion. Hook PreToolUse dijalankan.
2. Hook mengembalikan permissionDecision: "defer". Tool tidak dijalankan. Proses keluar dengan stop_reason: "tool_deferred" dan pemanggilan tool yang tertunda dipertahankan dalam transkrip.
3. Proses pemanggil membaca deferred_tool_use dari hasil SDK, menampilkan pertanyaan di UI miliknya sendiri, dan menunggu jawaban.
4. Proses pemanggil menjalankan claude -p --resume <session-id> dengan permission host yang sama. Pemanggilan tool yang sama menjalankan PreToolUse lagi.
5. Hook mengembalikan permissionDecision: "allow" dengan jawaban dalam updatedInput. Tool dijalankan dan Claude melanjutkan.

Bidang deferred_tool_use membawa id, name, dan input tool. input adalah parameter yang Claude hasilkan untuk pemanggilan tool, ditangkap sebelum eksekusi:

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

Tidak ada timeout atau batas retry. Sesi tetap di disk sampai Anda melanjutkannya, tunduk pada penyapuan retensi cleanupPeriodDays yang menghapus file sesi setelah 30 hari secara default, mengikuti aturan penyapuan retensi. Jika jawaban tidak siap saat Anda melanjutkan, hook dapat mengembalikan "defer" lagi dan proses keluar dengan cara yang sama. Proses pemanggil mengontrol kapan harus memecah loop dengan akhirnya mengembalikan "allow" atau "deny" dari hook.

"defer" hanya bekerja ketika Claude membuat satu pemanggilan tool dalam giliran. Jika Claude membuat beberapa pemanggilan tool sekaligus, "defer" diabaikan dengan peringatan dan tool melanjutkan melalui alur izin normal. Batasan ada karena resume hanya dapat menjalankan kembali satu tool: tidak ada cara untuk menunda satu pemanggilan dari batch tanpa meninggalkan yang lain tidak terselesaikan.

Jika tool yang ditunda tidak lagi tersedia saat Anda melanjutkan, proses keluar dengan stop_reason: "tool_deferred_unavailable" dan is_error: true sebelum hook dijalankan. Ini terjadi ketika server MCP yang menyediakan tool tidak terhubung untuk sesi yang dilanjutkan. Payload deferred_tool_use masih disertakan sehingga Anda dapat mengidentifikasi tool mana yang hilang.

PermissionRequest

Dijalankan ketika Claude Code akan menanyakan Anda untuk izin menggunakan tool. Dalam sesi yang tidak dapat menampilkan prompt, seperti subagents latar belakang dalam mode non-interaktif, Claude Code masih menjalankan hooks ini, dan jika tidak ada hook yang mengembalikan keputusan, itu menolak pemanggilan tool. Gunakan PermissionRequest decision control untuk mengizinkan atau menolak atas nama pengguna.

Gunakan event ini ketika Anda memerlukan sinyal saat Claude meminta izin menggunakan tool. Claude Code menjalankan hook Notification dengan tipe permission_prompt hanya setelah prompt menunggu sekitar enam detik.

Claude Code tidak menjalankan PermissionRequest hooks untuk network request perintah sandboxed. Untuk mendapatkan sinyal untuk prompt itu, gunakan tipe notifikasi permission_prompt.

Cocok pada nama tool, nilai yang sama seperti PreToolUse.

PermissionRequest input

PermissionRequest hooks menerima bidang tool_name dan tool_input seperti PreToolUse hooks, tetapi tanpa tool_use_id. Untuk MCP tool, mereka juga menerima objek mcp_server. Array permission_suggestions opsional berisi permission updates yang Claude Code sarankan untuk permintaan ini, seperti menambahkan aturan allow atau mengubah mode izin.

Array permission_suggestions bukan daftar opsi yang tepat yang Anda lihat, karena setiap dialog izin membangun opsi miliknya sendiri. Beberapa dialog, seperti yang untuk edit file, tidak membaca array sama sekali dan menurunkan opsi mereka dari permintaan itu sendiri. Dialog yang membacanya masih dapat menahan opsi yang sarannya tetap dalam array, misalnya ketika allowManagedPermissionRulesOnly menyembunyikan opsi penyimpanan aturan. Itu juga dapat menawarkan opsi yang tidak memiliki entri saran, seperti Yes, and switch to auto mode, yang mengubah mode izin secara langsung daripada melalui pembaruan izin.

PreToolUse hooks dijalankan sebelum setiap pemanggilan tool, terlepas dari apakah itu memerlukan izin. PermissionRequest hooks dijalankan hanya ketika Claude Code akan menanyakan Anda untuk izin, atau ketika itu akan sebaliknya auto-deny panggilan yang tidak dapat meminta. Tidak ada event yang dijalankan untuk 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 decision control

Hooks PermissionRequest dapat mengizinkan atau menolak permintaan izin. Selain bidang output JSON yang tersedia untuk semua hooks, skrip hook Anda dapat mengembalikan objek decision dengan bidang spesifik event ini:

Hook yang keluar 2 tanpa objek decision meninggalkan alur izin tidak berubah, dan stderr-nya dibuang. Hanya objek decision yang dapat memberikan atau menolak permintaan.

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

Permission update entries

Bidang output updatedPermissions dan bidang input permission_suggestions keduanya menggunakan array objek entry yang sama. Setiap entry memiliki type yang menentukan bidang lainnya, dan destination yang mengontrol di mana perubahan ditulis.

Bidang destination pada setiap entry menentukan apakah perubahan tetap dalam memori atau persisten ke file pengaturan.

Hook dapat mengembalikan salah satu dari permission_suggestions yang diterima sebagai output updatedPermissions miliknya sendiri.

PostToolUse

Dijalankan segera setelah tool selesai dengan sukses.

Cocok pada nama tool, nilai yang sama seperti PreToolUse.

Cocok lebih luas ketika nama tool bukan filter yang tepat:

• Untuk menjalankan hook setelah tool apa pun selesai dengan sukses, hilangkan matcher atau atur ke "*". Hook Anda kemudian dapat menemukan apa yang berubah sendiri, misalnya dengan menjalankan git status --porcelain, yang juga mencantumkan file yang tidak dilacak yang git diff lewatkan. Untuk pemanggilan tool yang gagal, tambahkan hook yang sama di bawah PostToolUseFailure.
• Untuk menjalankan hook ketika file tertentu berubah di disk, apa pun yang menulisnya, gunakan FileChanged. Claude Code tidak menjalankan hook PostToolUse yang cocok dengan Edit|Write ketika perintah Bash atau proses di luar Claude Code menulis ulang file yang sama.

PostToolUse input

Hooks PostToolUse dijalankan setelah tool sudah dijalankan dengan sukses. Input mencakup tool_input, argumen yang dikirim ke tool, dan tool_response, hasil yang dikembalikan. Skema yang tepat untuk keduanya tergantung pada tool. Path tool_input file-tool tiba dalam format yang sama seperti untuk PreToolUse: selalu absolut, dengan pemisah asli platform, jadi backslashes di Windows. Untuk MCP tool, input juga membawa objek 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 decision control

Hooks PostToolUse dapat memberikan umpan balik ke Claude setelah eksekusi tool. Selain bidang output JSON yang tersedia untuk semua hooks, skrip hook Anda dapat mengembalikan bidang spesifik event ini:

Contoh di bawah mengganti output pemanggilan Bash. Nilai pengganti cocok dengan bentuk output tool Bash:

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

Annotate a result for the auto mode classifier

Kembalikan classifierContext untuk mengirimkan catatan singkat tentang hasil pemanggilan tool ke pengklasifikasi auto mode daripada ke Claude. Pengklasifikasi tidak pernah menerima hasil tool sendiri, jadi bidang ini adalah cara yang didukung untuk memberitahunya sesuatu tentang apa yang dikembalikan panggilan sebelum itu meninjau tindakan yang lebih baru. Bidang memerlukan Claude Code v2.1.236 atau lebih baru.

Contoh di bawah memberitahu pengklasifikasi dari mana output query berasal:

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

Berapa banyak bobot yang diberikan pengklasifikasi pada catatan tergantung pada di mana Anda mengonfigurasi hook:

• Hooks yang dikonfigurasi dalam Claude Code: untuk hooks dari file pengaturan, plugins, skills, dan frontmatter agent, pengklasifikasi memperlakukan catatan sebagai konteks yang tidak diverifikasi yang disediakan aplikasi. Catatan tidak pernah menetapkan niat pengguna, dan jika itu mengklaim Anda menyetujui atau meminta sesuatu, pengklasifikasi memeriksa klaim itu terhadap pesan Anda sendiri dalam percakapan
• Callback in-process Agent SDK: ketika aplikasi yang menyematkan Claude Code mendaftarkan hook sebagai callback TypeScript SDK dan mengembalikan catatan selama sesi langsung, pengklasifikasi dapat menimbang pernyataan pengguna yang disampaikan dalam catatan sebagai niat pengguna. Pernyataan seperti itu dapat memenuhi persyaratan persetujuan yang akan diterima pengklasifikasi dari pesan yang Anda kirim, tetapi tidak pernah mengangkat blok yang pesan Anda sendiri tidak bisa angkat juga. Setelah sesi dilanjutkan, Claude Code memperlakukan catatan yang dipulihkan sebagai konteks yang tidak diverifikasi. Ketika hooks dari kedua grup menganotasi panggilan yang sama, pengklasifikasi memperlakukan catatan gabungan sebagai konteks yang tidak diverifikasi

Claude Code menerapkan batas-batas ini ketika mengirimkan catatan:

• Panjang: Claude Code membatasi catatan untuk satu pemanggilan tool pada 2.000 karakter dan memotong sisanya. Batas dibagikan di seluruh setiap hook yang merespons panggilan itu
• Respons sinkron saja: Claude Code mengabaikan bidang dalam respons hook yang berjalan di latar belakang, karena respons itu tiba setelah Claude Code mencatat hasil tool
• Panggilan yang tidak dicatat pengklasifikasi: transkrip pengklasifikasi menghilangkan pencarian read-only seperti pembacaan file dan pencarian. Claude Code membuang catatan yang dilampirkan pada salah satu panggilan itu
• Interaksi dengan penulisan ulang: ketika catatan menjelaskan output yang Anda ganti dengan updatedToolOutput, kembalikan kedua bidang dalam respons hook yang sama. Claude Code menjatuhkan catatan jika penulisan ulang itu ditolak atau penulisan ulang hook lain menggantinya. Claude Code mengirimkan catatan yang Anda kembalikan tanpa penulisan ulang bahkan ketika hook lain menulis ulang output

PostToolUseFailure

Dijalankan ketika tool yang mulai dijalankan gagal: tool melempar kesalahan, atau tool MCP mengembalikan hasil kesalahan. Gunakan ini untuk mencatat kegagalan, mengirim alert, atau memberikan umpan balik korektif ke Claude.

Cocok pada nama tool, nilai yang sama seperti PreToolUse.

PostToolUseFailure input

PostToolUseFailure hooks menerima bidang tool_name dan tool_input yang sama seperti PostToolUse, bersama dengan informasi kesalahan sebagai bidang tingkat atas. Untuk MCP tool, mereka juga menerima objek mcp_server. Misalnya, perintah npm test yang gagal mungkin memberikan:

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

String error umumnya teks yang sama yang diterima Claude sebagai hasil tool yang gagal. Format-nya bervariasi menurut tool dan kegagalan. Kunci hook Anda pada tool_name, is_interrupt, dan baris pertama Exit code N; perlakukan sisa string sebagai teks tampilan, bukan format yang stabil.

• Untuk Bash dan PowerShell, perintah yang dijalankan dan keluar menghasilkan baris pertama Exit code N, kemudian output apa pun yang dihasilkan perintah sebagai satu blok dengan stdout dan stderr yang diinterleave
• Payload juga dapat membawa pesan kegagalan telanjang tanpa baris kode keluar, ketika Claude Code tidak dapat memulai proses shell itu sendiri
• Claude Code middle-truncates string panjang di sekitar penanda ... [N characters truncated] ..., dan dapat menyisipkan baris miliknya sendiri, seperti Command timed out after 2m 0s

PostToolUseFailure decision control

Hooks PostToolUseFailure dapat memberikan konteks ke Claude setelah kegagalan tool. Selain bidang output JSON yang tersedia untuk semua hooks, skrip hook Anda dapat mengembalikan bidang spesifik event ini:

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

PostToolBatch

Dijalankan sekali setelah setiap tool call dalam batch telah terselesaikan, sebelum Claude Code mengirimkan permintaan berikutnya ke model. PostToolUse dijalankan sekali per tool, yang berarti dijalankan secara bersamaan ketika Claude membuat pemanggilan tool paralel. PostToolBatch dijalankan tepat sekali dengan batch lengkap, jadi ini adalah tempat yang tepat untuk menyuntikkan konteks yang bergantung pada set tools yang dijalankan daripada pada tool tunggal. Tidak ada matcher untuk event ini.

PostToolBatch input

Selain bidang input umum, PostToolBatch hooks menerima tool_calls, array yang menjelaskan setiap pemanggilan tool dalam batch:

{
  "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\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

tool_response berisi konten yang sama yang diterima model dalam blok tool_result yang sesuai. Nilainya adalah string yang diserialisasi atau array blok konten, persis seperti yang dikeluarkan tool. Untuk Read, itu berarti teks dengan awalan nomor baris daripada konten file mentah. Respons dapat besar, jadi hanya parse bidang yang Anda butuhkan.

PostToolBatch decision control

Hooks PostToolBatch dapat menyuntikkan konteks untuk Claude. Selain bidang output JSON yang tersedia untuk semua hooks, skrip hook Anda dapat mengembalikan bidang spesifik event ini:

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

Mengembalikan decision: "block" atau continue: false menghentikan loop agentic sebelum panggilan model berikutnya. Pesan pemblokiran berasal dari JSON reason atau stopReason, atau dari stderr pada keluar 2. Anda melihatnya sebagai peringatan dalam transkrip, dan itu tetap dalam percakapan, jadi Claude melihatnya ketika percakapan berlanjut.

PermissionDenied

Dijalankan ketika auto mode menolak pemanggilan tool, termasuk ketika itu menolak tanpa putusan pengklasifikasi karena pemeriksaan keamanan terpisah dari auto mode menolak permintaan pengklasifikasi sendiri atau respons-nya tidak diparse. Hook ini hanya dijalankan dalam auto mode: itu tidak dijalankan ketika Anda secara manual menolak dialog izin, ketika hook PreToolUse memblokir panggilan, atau ketika aturan deny cocok. Gunakan untuk mencatat penolakan, menyesuaikan konfigurasi, atau memberitahu model itu dapat mencoba lagi pemanggilan tool.

Cocok pada nama tool, nilai yang sama seperti PreToolUse.

PermissionDenied input

Selain bidang input umum, PermissionDenied hooks menerima tool_name, tool_input, tool_use_id, dan reason. Untuk MCP tool, mereka juga menerima objek 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 decision control

PermissionDenied hooks dapat memberitahu model itu dapat mencoba lagi pemanggilan tool yang ditolak. Kembalikan objek JSON dengan hookSpecificOutput.retry diatur ke true:

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

Ketika retry adalah true, Claude Code menambahkan pesan ke percakapan memberitahu model itu dapat mencoba lagi pemanggilan tool. Penolakan itu sendiri tidak dibatalkan. Jika hook Anda tidak mengembalikan JSON, atau mengembalikan retry: false, penolakan tetap dan model menerima pesan penolakan asli.

Claude Code mengabaikan retry: true ketika pengklasifikasi menghasilkan tidak ada putusan pada tindakan: respons-nya tidak diparse, atau pemeriksaan keamanan terpisah dari auto mode menolak permintaan pengklasifikasi sendiri. Untuk penolakan itu, Claude Code sudah memberitahu model dalam pesan penolakan apakah harus mencoba lagi nanti atau melanjutkan.

Notification

Dijalankan ketika Claude Code mengirimkan notifikasi. Cocok pada tipe notifikasi. Hilangkan matcher untuk menjalankan hooks untuk semua tipe notifikasi.

Anda menerima hook events ini bahkan dengan notifikasi desktop dimatikan: pengaturan preferredNotifChannel, termasuk notifications_disabled, hanya mengubah cara Anda diperingatkan, bukan apakah hook Anda dijalankan.

Tipe agent_needs_input dan agent_completed memerlukan Claude Code v2.1.198 atau lebih baru.

Tipe quota_auto_resume_fired, quota_auto_resume_stale, dan quota_auto_resume_disabled memerlukan Claude Code v2.1.234 atau lebih baru.

Dalam sesi terminal, permission_prompt untuk network request perintah sandboxed memerlukan Claude Code v2.1.246 atau lebih baru.

agent_needs_input untuk pertanyaan setup terminal teammate memerlukan Claude Code v2.1.248 atau lebih baru.

Claude Code waktu permission_prompt berbeda dalam sesi di mana itu mengirimkan permintaan izin ke callback canUseTool Agent SDK, yang merupakan cara Claude Desktop dan ekstensi VS Code menyelenggarakan Claude Code:

• Harapkan permission_prompt sekitar enam detik setelah Claude meminta izin. Claude Code tidak menundanya sementara Anda mengetik.
• Jika Anda atau hook PermissionRequest menjawab lebih cepat, Claude Code tidak menjalankan permission_prompt.
• Atur CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS ke 1 untuk mematikan permission_prompt dalam sesi ini.

Sebelum v2.1.233, permission_prompt tidak dijalankan dalam sesi ini.

Gunakan matchers terpisah untuk menjalankan handler berbeda tergantung pada tipe notifikasi. Konfigurasi ini memicu skrip alert khusus izin ketika Claude memerlukan persetujuan izin dan notifikasi berbeda ketika Claude telah idle:

{
  "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 input

Selain bidang input umum, Notification hooks menerima message dengan teks notifikasi, title opsional, dan notification_type menunjukkan tipe mana yang dijalankan.

{
  "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 hooks tidak dapat memblokir atau memodifikasi notifikasi. Claude Code membuang systemMessage dan continue mereka tetapi masih memancarkan terminalSequence, yang merupakan apa yang contoh notifikasi desktop andalkan. Notification hooks dimaksudkan untuk efek samping seperti meneruskan notifikasi ke layanan eksternal.

SubagentStart

Dijalankan ketika Claude spawn subagent dengan tool Agent, ketika Claude melanjutkan subagent, dan setiap kali agent team in-process teammate menangani pesan baru. Mendukung matchers untuk memfilter berdasarkan nama tipe agent. Untuk agent bawaan, ini adalah nama agent seperti general-purpose, Explore, atau Plan. Untuk custom subagents, ini adalah bidang name dari frontmatter agent, bukan nama file.

Untuk subagents yang dikirim oleh plugin, tipe agent adalah pengenal bersifat plugin seperti my-plugin:reviewer, bukan nama frontmatter biasa. Titik dua menempatkan nama bersifat plugin pada jalur ekspresi reguler, jadi jangkar matcher dengan ^ dan $ untuk kecocokan yang tepat: ^my-plugin:reviewer$.

SubagentStart input

Selain bidang input umum, SubagentStart hooks menerima agent_id dengan pengenal unik untuk subagent dan agent_type dengan nama agent yang matcher filter.

{
  "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 hooks tidak dapat memblokir pembuatan subagent, tetapi mereka dapat menyuntikkan konteks ke subagent. Selain bidang output JSON yang tersedia untuk semua hooks, Anda dapat mengembalikan:

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

Ketika hook dijalankan lagi untuk subagent yang sama, Claude Code menyuntikkan konteks yang dikembalikan hanya ketika konteks subagent tidak sudah menyimpan salinan dari run yang lebih awal. Salinan yang disuntikkan saat peluncuran tetap di tempat, meninggalkan prompt cache subagent utuh. Setelah auto-compaction membuang salinan itu, Claude Code menyuntikkan konteks run berikutnya lagi.

SubagentStop

Dijalankan ketika subagent Claude Code telah selesai merespons. Cocok pada tipe agent, nilai yang sama seperti SubagentStart.

SubagentStop input

Selain bidang input umum, SubagentStop hooks menerima stop_hook_active, agent_id, agent_type, agent_transcript_path, dan last_assistant_message. Bidang agent_type adalah nilai yang digunakan untuk pemfilteran matcher. transcript_path adalah transkrip sesi utama, sementara agent_transcript_path adalah transkrip subagent sendiri yang disimpan dalam folder subagents/ bersarang. Bidang last_assistant_message berisi konten teks respons akhir subagent, jadi hooks dapat mengaksesnya tanpa mengurai file transkrip.

Tidak setiap event SubagentStop berasal dari subagent yang di-spawn Claude. Claude Code juga menjalankan agent internal untuk beberapa fiturnya sendiri, seperti saran prompt dan pertanyaan sampingan /btw, dan SubagentStop juga dijalankan ketika salah satunya selesai. Untuk events tersebut, agent_type adalah nama agent yang dijalankan sebagai sesi itu sendiri, seperti yang diatur dengan --agent atau pengaturan agent, dan string kosong ketika sesi berjalan tanpa agent.

matcher yang menyebutkan tipe agent tidak cocok dengan agent_type kosong. Hook yang matcher-nya dihilangkan, "", atau "*", atau berupa ekspresi reguler yang cocok dengan string kosong, juga dijalankan untuk events dengan agent_type kosong.

Pada Claude Code v2.1.271 atau lebih baru, subagent yang berjalan dengan tool SubagentHandback mengirimkan laporannya melalui tool itu sebelum berhenti. Bidang last_assistant_message kemudian menyimpan teks penutup subagent, jika ada, yang bukan laporan yang disampaikan. Laporan adalah input message panggilan itu, yang hook PreToolUse atau PostToolUse yang cocok pada SubagentHandback menerima sebagai tool_input.message.

SubagentStop hooks juga menerima array background_tasks dan session_crons yang dijelaskan di bawah Stop input. Kedua array bersifat scoped ke sesi induk, bukan subagent.

{
  "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 hooks menggunakan format kontrol keputusan yang sama seperti Stop hooks, termasuk hookSpecificOutput.additionalContext dengan hookEventName diatur ke "SubagentStop", untuk umpan balik non-error yang membuat subagent tetap berjalan. Mengembalikan decision: "block" dengan reason membuat subagent tetap berjalan dan mengirimkan reason ke subagent sebagai instruksi berikutnya. Untuk menyuntikkan konteks ke sesi induk setelah subagent kembali, gunakan hook PostToolUse pada tool Agent sebagai gantinya.

TaskCreated

Dijalankan ketika tugas sedang dibuat melalui tool TaskCreate. Gunakan ini untuk menegakkan konvensi penamaan, memerlukan deskripsi tugas, atau mencegah tugas tertentu dari dibuat. Dalam sesi tanpa Task tools, event ini tidak dijalankan.

TaskCreated hooks tidak mendukung matchers dan dijalankan pada setiap kemunculan.

TaskCreated input

Selain bidang input umum, TaskCreated hooks menerima task_id, task_subject, dan secara opsional task_description, teammate_name, dan 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 decision control

Hook TaskCreated dapat memblokir pembuatan dengan dua cara. Baik cara, Claude Code menghapus tugas dan mengembalikan pesan Anda ke Claude sebagai kesalahan tool. Claude Code mengabaikan continue: false dari event ini dan Claude terus bekerja.

• Kode keluar 2: Claude Code mengembalikan teks stderr sebagai pesan.
• JSON {"decision": "block", "reason": "..."}: Claude Code mengembalikan reason sebagai pesan.

Contoh ini memblokir tugas yang subjeknya tidak mengikuti format yang diperlukan:

#!/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

Dijalankan ketika tugas sedang ditandai sebagai selesai. Ini dijalankan dalam dua situasi: ketika agent apa pun secara eksplisit menandai tugas sebagai selesai melalui tool TaskUpdate, atau ketika agent team teammate menyelesaikan giliran dengan tugas yang sedang berlangsung. Gunakan ini untuk menegakkan kriteria penyelesaian seperti passing tests atau lint checks sebelum tugas dapat ditutup.

TaskCompleted hooks tidak mendukung matchers dan dijalankan pada setiap kemunculan.

TaskCompleted input

Selain bidang input umum, TaskCompleted hooks menerima task_id, task_subject, dan secara opsional task_description, teammate_name, dan 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 decision control

TaskCompleted hooks mendukung dua cara untuk mengontrol penyelesaian tugas:

• Kode keluar 2: tugas tidak ditandai sebagai selesai dan pesan stderr diumpankan kembali ke model sebagai umpan balik.
• JSON {"continue": false, "stopReason": "..."}: ketika teammate yang menyelesaikan gilirannya memicu event, menghentikan teammate sepenuhnya, mencocokkan perilaku hook Stop. stopReason ditampilkan ke pengguna. Ketika tool TaskUpdate memicu event, Claude Code mengabaikan continue: false; kode keluar 2 masih memblokir penyelesaian.

Contoh ini menjalankan tests dan memblokir penyelesaian tugas jika gagal:

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

# Jalankan 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

Dijalankan ketika agent Claude Code utama telah selesai merespons. Tidak dijalankan jika penghentian terjadi karena interupsi pengguna. Kesalahan API menjalankan StopFailure sebagai gantinya.

Stop input

Selain bidang input umum, Stop hooks menerima stop_hook_active, last_assistant_message, background_tasks, dan session_crons. Bidang stop_hook_active adalah true ketika Claude Code sudah melanjutkan sebagai hasil dari stop hook. Periksa nilai ini atau proses transkrip untuk menghindari memblokir pada kondisi yang tidak akan pernah terselesaikan. Claude Code menimpa hook dan mengakhiri giliran setelah 8 blok berturut-turut.

Bidang last_assistant_message berisi konten teks respons akhir Claude, jadi hooks dapat mengaksesnya tanpa mengurai file transkrip. Untuk hooks yang bertindak pada giliran yang baru selesai, seperti hooks read-aloud atau notifikasi, gunakan bidang ini daripada membaca transcript_path: file transkrip tidak dijamin menyertakan pesan akhir pada Stop time di semua versi.

Array background_tasks dan session_crons memungkinkan hooks membedakan "sesi selesai" dari "sesi dijeda menunggu pekerjaan latar belakang untuk membangunkannya kembali". Kedua array hadir ketika registri tugas dapat dijangkau dan kosong ketika tidak ada yang sedang berlangsung atau dijadwalkan.

Setiap entry dalam background_tasks menjelaskan satu tugas yang sedang berlangsung dan menggunakan bidang-bidang ini:

Setiap entry dalam session_crons menjelaskan satu wakeup terjadwal yang bersifat sesi, bersumber dari CronCreate, ScheduleWakeup, dan /loop:

Contoh ini menunjukkan input Stop dengan satu tugas shell yang sedang berlangsung dan satu cron berulang:

{
  "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 decision control

Hooks Stop dan SubagentStop dapat mengontrol apakah Claude melanjutkan. Selain bidang output JSON yang tersedia untuk semua hooks, skrip hook Anda dapat mengembalikan bidang spesifik event ini:

Hook yang memblokir dengan keluar 2 merutekan dengan cara yang sama seperti reason: Claude menerima pesan stderr sebagai penjelasan mengapa itu harus melanjutkan.

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

Gunakan additionalContext ketika hook bekerja seperti yang dirancang dan memberikan panduan Claude, seperti "jalankan test suite sebelum selesai". Ini membuat percakapan terus berlanjut melalui proteksi loop yang sama seperti decision: "block", yaitu input stop_hook_active dan batas 8-kontinuasi berturut-turut, tetapi transkrip memberi label Stop hook feedback dan tidak ada notifikasi kesalahan hook yang ditampilkan:

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

StopFailure

Dijalankan alih-alih Stop ketika giliran berakhir karena kesalahan API. Claude Code mengabaikan output hook dan kode keluar, selain dari terminalSequence. Gunakan ini untuk mencatat kegagalan, mengirim alert, atau mengambil tindakan pemulihan ketika Claude tidak dapat menyelesaikan respons karena rate limits, masalah autentikasi, atau kesalahan API lainnya.

StopFailure input

Selain bidang input umum, StopFailure hooks menerima error, error_details opsional, dan last_assistant_message opsional. Bidang error mengidentifikasi tipe kesalahan dan digunakan untuk pemfilteran 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 hooks tidak memiliki kontrol keputusan. Mereka dijalankan untuk tujuan notifikasi dan logging saja.

TeammateIdle

Dijalankan ketika agent team teammate akan menjadi idle setelah menyelesaikan giliran. Gunakan ini untuk menegakkan quality gates sebelum teammate berhenti bekerja, seperti memerlukan passing lint checks atau memverifikasi bahwa file output ada.

TeammateIdle hooks tidak mendukung matchers dan dijalankan pada setiap kemunculan.

TeammateIdle input

Selain bidang input umum, TeammateIdle hooks menerima teammate_name dan 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 decision control

TeammateIdle hooks mendukung dua cara untuk mengontrol perilaku teammate:

• Kode keluar 2: teammate menerima pesan stderr sebagai umpan balik dan terus bekerja alih-alih menjadi idle.
• JSON {"continue": false, "stopReason": "..."}: menghentikan teammate sepenuhnya, mencocokkan perilaku hook Stop. stopReason ditampilkan ke pengguna.

Contoh ini memeriksa bahwa artefak build ada sebelum mengizinkan teammate menjadi idle:

#!/bin/bash

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

exit 0

ConfigChange

Dijalankan ketika file konfigurasi berubah selama sesi. Gunakan ini untuk mengaudit perubahan pengaturan, menegakkan kebijakan keamanan, atau memblokir modifikasi tidak sah ke file konfigurasi.

Claude Code menjalankan ConfigChange hooks ketika file pengaturan, file kebijakan terkelola, atau file skill berubah. Untuk kebijakan terkelola, itu menjalankan mereka hanya ketika managed-settings.json atau file dalam managed-settings.d/ berubah. Itu menerapkan server-managed settings dan perubahan ke preferensi terkelola macOS atau kebijakan registri Windows tanpa menjalankan mereka. Di WSL dengan wslInheritsWindowsSettings, itu juga menerapkan file pengaturan terkelola Windows-side yang berubah pada polling kebijakan-nya tanpa menjalankan mereka.

Matcher memfilter pada sumber konfigurasi:

Contoh ini mencatat semua perubahan konfigurasi untuk audit keamanan:

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

ConfigChange input

Selain bidang input umum, ConfigChange hooks menerima source dan secara opsional file_path. Bidang source menunjukkan tipe konfigurasi mana yang berubah, dan file_path menyediakan path ke file spesifik yang dimodifikasi.

{
  "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 decision control

ConfigChange hooks dapat memblokir perubahan konfigurasi dari berlaku. Gunakan kode keluar 2 atau JSON decision untuk mencegah perubahan. Ketika diblokir, pengaturan baru tidak diterapkan ke sesi yang berjalan.

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

Perubahan policy_settings tidak dapat diblokir. Hooks masih dijalankan untuk sumber policy_settings ketika file pengaturan terkelola pada mesin berubah, jadi Anda dapat menggunakannya untuk mencatat edit itu, tetapi keputusan blocking apa pun diabaikan. Ini memastikan pengaturan yang dikelola enterprise selalu berlaku. Claude Code tidak menjalankan ConfigChange hooks ketika server-managed settings tiba atau refresh.

Claude Code bertindak atas keputusan pemblokiran dari output JSON ConfigChange hook dan membuang systemMessage dan continue. Perubahan yang diblokir tidak menampilkan pesan kepada Anda atau Claude, baik Anda memblokir dengan reason atau dengan stderr pada keluar 2. Claude Code hanya menulis baris ke debug log.

CwdChanged

Dijalankan ketika perintah shell dalam percakapan utama mengubah direktori kerja, misalnya ketika Claude menjalankan perintah cd. Gunakan ini untuk bereaksi terhadap perubahan direktori: muat ulang variabel lingkungan, aktifkan toolchains khusus proyek, atau jalankan skrip setup secara otomatis. Berpasangan dengan FileChanged untuk tools seperti direnv yang mengelola lingkungan per-direktori.

CwdChanged hooks memiliki akses ke CLAUDE_ENV_FILE. Variabel yang ditulis ke file itu bertahan ke perintah Bash berikutnya sampai event CwdChanged berikutnya, ketika Claude Code menghapusnya.

CwdChanged tidak mendukung matchers dan dijalankan pada setiap perubahan direktori.

CwdChanged input

Selain bidang input umum, CwdChanged hooks menerima old_cwd dan 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 output

Selain bidang output JSON yang tersedia untuk semua hooks, CwdChanged hooks dapat mengembalikan watchPaths untuk secara dinamis menetapkan path file mana yang FileChanged pantau:

CwdChanged hooks tidak memiliki kontrol keputusan. Mereka tidak dapat memblokir perubahan direktori.

Claude Code membaca watchPaths dan systemMessage dari output JSON mereka dan membuang continue. Dalam sesi interaktif, itu menampilkan systemMessage sebagai notifikasi terminal singkat. Pesan tidak mencapai aliran pesan SDK.

DirectoryAdded

Dijalankan setelah Anda menambahkan direktori kerja mid-session dengan perintah /add-dir, atau setelah klien SDK menambahkan satu dengan permintaan kontrol register_repo_root. Gunakan ini untuk menyiapkan repositori yang baru ditambahkan, misalnya dengan menginstal dependensinya.

Claude Code tidak menjalankan event ini ketika:

• Anda meneruskan direktori dengan flag startup --add-dir; SessionStart mencakup direktori itu
• Anda menambahkan direktori di tab /permissions Workspace
• Anda menambahkan direktori yang sudah merupakan direktori kerja atau di dalam satu

Claude Code menjalankan DirectoryAdded setelah menyegarkan status sandbox dan izin, jadi tools sandboxed sudah melihat direktori baru ketika hook Anda dijalankan. Perintah hook itu sendiri berjalan tanpa sandbox.

Claude Code tidak menunggu hook: penambahan selesai segera, dan hook dijalankan di latar belakang dengan timeout default 600 detik.

Matcher memfilter pada cara direktori ditambahkan:

DirectoryAdded input

Selain bidang input umum, DirectoryAdded hooks menerima directory dan 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 hooks tidak memiliki kontrol keputusan. Mereka tidak dapat memblokir penambahan, yang sudah selesai ketika hook dijalankan. Claude Code membuang bidang continue dari output JSON mereka dan menampilkan sisanya berbeda per sumber:

• slash_command: Claude Code mengirimkan output systemMessage hook ke Claude sebagai konteks pada giliran percakapan berikutnya, daripada menampilkannya kepada Anda. Jumlah hook yang gagal muncul dalam transkrip. Output kegagalan lengkap masuk ke debug log
• register_repo_root: Claude Code menulis output systemMessage dan output kegagalan ke debug log saja

FileChanged

Dijalankan ketika file yang dipantau berubah di disk. Claude Code mendeteksi perubahan dengan filesystem watcher, bukan dengan memeriksa pemanggilan tool, jadi itu menjalankan hook tidak peduli apa yang mengubah file: pemanggilan tool Edit atau Write, skrip yang dijalankan Claude dengan Bash, atau proses di luar Claude Code sepenuhnya. Penggunaan umum adalah memuat ulang variabel lingkungan ketika file konfigurasi proyek berubah.

Bidang matcher untuk event ini melayani dua peran:

• Bangun daftar watch: nilai dibagi pada | dan setiap segmen terdaftar sebagai nama file literal di direktori kerja, jadi ".envrc|.env" menonton tepat dua file itu. Pola regex tidak berguna di sini: nilai seperti ^\.env akan menonton file yang secara harfiah bernama ^\.env.
• Filter hooks mana yang dijalankan: ketika file yang dipantau berubah, nilai yang sama memfilter grup hook mana yang dijalankan menggunakan aturan matcher standar terhadap basename file yang berubah.

Contoh ini menormalkan line endings dalam data.csv setelah perubahan apa pun, termasuk pemanggilan tool Bash atau skrip eksternal yang menulis ulang file:

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

Hook membaca path file yang berubah dari bidang file_path dari JSON input di stdin. Guard grep-nya menguji hal yang sama yang perl hapus, CR di akhir baris, jadi run setelah normalisasi keluar tanpa menyentuh file. Guard yang lebih longgar loop selamanya, karena perl -i menulis ulang file bahkan ketika itu mengganti tidak ada dan Claude Code menjalankan hook lagi setelah setiap penulisan ulang. Simpan skrip ini di /path/to/normalize-line-endings.sh dan buat dapat dieksekusi:

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

Untuk mengkonfirmasi hook bekerja, minta Claude untuk menambahkan baris CRLF ke data.csv dengan perintah Bash. Claude Code menjalankan hook dan file berakhir dengan line endings LF.

Untuk menonton file yang tidak dapat Anda beri nama di muka, kembalikan watchPaths dari hook untuk memperbarui daftar watch secara dinamis. Claude Code memulai watcher hanya ketika sesuatu memberi nama file untuk ditonton, jadi seed daftar dengan grup FileChanged yang matcher-nya memberi nama setidaknya satu file, atau dengan hook SessionStart atau CwdChanged yang mengembalikan watchPaths. Matcher masih memfilter grup hook mana yang dijalankan ketika file yang dipantau berubah, jadi berikan grup yang menangani path dinamis matcher yang dihilangkan, yang cocok dengan setiap file yang dipantau dan tidak menambahkan apa pun ke daftar watch. Matcher "*" juga cocok dengan setiap file, tetapi Claude Code mendaftarkannya dalam daftar watch seperti nilai lainnya, sebagai file literal bernama *.

FileChanged hooks memiliki akses ke CLAUDE_ENV_FILE. Variabel yang ditulis ke file itu bertahan ke perintah Bash berikutnya sampai event CwdChanged berikutnya, ketika Claude Code menghapusnya.

FileChanged input

Selain bidang input umum, FileChanged hooks menerima file_path dan 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 output

Selain bidang output JSON yang tersedia untuk semua hooks, FileChanged hooks dapat mengembalikan watchPaths untuk secara dinamis memperbarui path file mana yang dipantau:

FileChanged hooks tidak memiliki kontrol keputusan. Mereka tidak dapat memblokir perubahan file dari terjadi.

Claude Code membaca watchPaths dan systemMessage dari output JSON mereka dan membuang continue. Dalam sesi interaktif, itu menampilkan systemMessage sebagai notifikasi terminal singkat. Pesan tidak mencapai aliran pesan SDK.

WorktreeCreate

Dijalankan ketika worktree sedang dibuat, baik dari claude --worktree, dari subagent menggunakan isolation: "worktree", atau untuk sesi latar belakang yang Claude Code isolasi dalam worktree-nya sendiri. Secara default Claude Code membuat salinan kerja terisolasi dengan git worktree. Mengonfigurasi hook WorktreeCreate menggantikan perilaku git default itu, memungkinkan Anda menggunakan sistem kontrol versi berbeda seperti SVN, Perforce, atau Mercurial.

Karena hook menggantikan perilaku default sepenuhnya, .worktreeinclude tidak diproses. Jika Anda perlu menyalin file konfigurasi lokal seperti .env ke worktree baru, lakukan di dalam skrip hook Anda.

Hook harus mengembalikan path ke direktori worktree yang dibuat. Claude Code menggunakan path ini sebagai direktori kerja untuk sesi terisolasi. Lihat WorktreeCreate output untuk cara setiap tipe hook mengembalikan path.

Contoh ini membuat salinan kerja SVN dan mencetak path untuk Claude Code gunakan. Ganti URL repositori dengan milik Anda sendiri:

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

Hook membaca name worktree dari input JSON di stdin, melakukan checkout salinan segar ke direktori baru, dan mencetak path direktori. echo pada baris terakhir adalah apa yang Claude Code baca sebagai path worktree. Alihkan output lainnya ke stderr sehingga tidak mengganggu path.

WorktreeCreate input

Selain bidang input umum, WorktreeCreate hooks menerima bidang name. Ini adalah pengenal slug untuk worktree baru, baik ditentukan oleh pengguna atau auto-generated, misalnya 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 output

WorktreeCreate hooks tidak menggunakan model keputusan allow/block standar. Sebaliknya, kesuksesan atau kegagalan hook menentukan hasil. Hook harus mengembalikan path ke direktori worktree yang dibuat:

• Command hooks (type: "command"): cetak path sebagai baris non-kosong terakhir dari stdout. Claude Code menghapus kode escape ANSI sebelum membaca baris itu, jadi banner startup shell yang dicetak sebelum echo Anda diabaikan. Alihkan output hook lainnya ke stderr.
• HTTP hooks (type: "http"): kembalikan { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } dalam badan respons.

Jika hook gagal atau tidak menghasilkan path, pembuatan worktree gagal dengan kesalahan.

Claude Code menyelesaikan path relatif terhadap direktori tempat hook dijalankan, meruntuhkan segmen . atau .. apa pun di dalamnya. Jika path yang dihasilkan bukan direktori yang dapat dimasuki Claude Code, sesi mencetak kesalahan yang menamai path dan keluar dengan kode 1.

Claude Code menolak path absolut yang berisi segmen . atau .., dan path apa pun yang melewati symlink di bawah akar repositori, karena symlink yang berkomitmen ke repositori dapat mengarahkan worktree di luarnya. Kesalahan menamai komponen yang ditolak. Kembalikan path yang dinormalisasi yang tidak melewati symlink di dalam repositori. Sebelum v2.1.216, pembuatan worktree mengikuti path hook tanpa screening ini.

WorktreeRemove

Dijalankan ketika worktree sedang dihapus. Ini adalah pasangan cleanup untuk WorktreeCreate. Event dijalankan ketika:

• Anda keluar dari sesi --worktree dan memilih untuk menghapusnya
• Subagent dengan isolation: "worktree" selesai
• Anda menghapus sesi latar belakang yang worktree-nya dibuat hook

Untuk git-based worktrees, Claude Code menangani cleanup secara otomatis dengan git worktree remove. Jika Anda mengonfigurasi hook WorktreeCreate untuk sistem kontrol versi non-git, pasangkan dengan hook WorktreeRemove untuk menangani cleanup. Tanpanya, direktori worktree ditinggalkan di disk.

Claude Code membuang bidang output JSON dari hook WorktreeRemove, seperti systemMessage dan continue.

Untuk penghapusan sesi latar belakang, Claude Code memverifikasi path worktree yang disimpan sebelum menjalankan hook dan menolak path yang merupakan symlink atau melewati satu di bawah akar repositori. Hook dijalankan untuk worktree yang masih berisi file hanya ketika Anda mengkonfirmasi penghapusan dalam agent view; untuk worktree seperti itu, claude rm menyimpan sesi dan worktree sebagai gantinya. Sebelum v2.1.216, hook dijalankan pada path yang disimpan tanpa pemeriksaan ini.

Claude Code meneruskan path yang dikembalikan oleh WorktreeCreate sebagai worktree_path dalam input hook. Contoh ini membaca path itu dan menghapus direktori:

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

WorktreeRemove input

Selain bidang input umum, WorktreeRemove hooks menerima bidang worktree_path, yang merupakan path absolut ke worktree yang sedang dihapus.

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

Kode keluar hook WorktreeRemove menentukan hasil. Ketika hook keluar non-zero dan direktori di worktree_path masih ada setelahnya, penghapusan gagal:

• Worktree tetap di disk, dan perintah hook dan stderr masuk ke debug log.
• Jika Anda menghapus sesi latar belakang, sesi tetap juga. Pesan penolakan dalam agent view melaporkan bagaimana hook berakhir, seperti exited 1, mengutip awal stderr-nya, dan mengatakan apakah menghapus sesi lagi menghapus direktori bagaimanapun.

PreCompact

Dijalankan sebelum Claude Code akan menjalankan operasi compact.

Nilai matcher menunjukkan apakah compaction dipicu secara manual atau otomatis:

Keluar dengan kode 2 untuk memblokir compaction. Untuk manual /compact, pesan stderr ditampilkan ke pengguna. Anda juga dapat memblokir dengan mengembalikan JSON dengan "decision": "block".

Memblokir automatic compaction memiliki efek berbeda tergantung pada kapan dijalankan. Jika compaction dipicu secara proaktif sebelum batas konteks, Claude Code melewatinya dan percakapan berlanjut tanpa compaction. Jika compaction dipicu untuk pulih dari kesalahan batas konteks yang sudah dikembalikan oleh API, kesalahan yang mendasar muncul dan permintaan saat ini gagal.

Claude Code membuang bidang systemMessage dan continue dari hook PreCompact.

PreCompact input

Selain bidang input umum, PreCompact hooks menerima trigger dan custom_instructions. Untuk manual, custom_instructions berisi apa yang diteruskan pengguna ke /compact dan null ketika mereka tidak meneruskan apa pun. Untuk auto, custom_instructions adalah 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

Dijalankan setelah Claude Code menyelesaikan operasi compact. Gunakan event ini untuk bereaksi terhadap status compacted baru, misalnya untuk mencatat ringkasan yang dihasilkan atau memperbarui status eksternal. Claude Code membuang bidang systemMessage dan continue dari hook PostCompact.

Nilai matcher yang sama berlaku seperti untuk PreCompact:

PostCompact input

Selain bidang input umum, PostCompact hooks menerima trigger dan compact_summary. Bidang compact_summary berisi ringkasan percakapan yang dihasilkan oleh operasi compact.

{
  "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 hooks tidak memiliki kontrol keputusan. Mereka tidak dapat mempengaruhi hasil compaction tetapi dapat melakukan tugas follow-up.

PreModelSwitch

Dijalankan sebelum Claude Code menerapkan perubahan model yang Anda atau klien minta. Gunakan untuk memblokir switch, memerlukan konfirmasi, atau menampilkan apa yang akan dibiayai switch sebelum terjadi.

PreModelSwitch memerlukan Claude Code v2.1.251 atau lebih baru. Claude Code menjalankannya untuk permintaan ini:

• /model <name> dan picker /model
• Picker model Option+P atau Alt+P
• Pengaturan Model dalam /config
• Mengaktifkan fast mode ketika itu mengubah model sesi
• Permintaan set_model, atau perubahan model dalam permintaan apply_flag_settings, dari host Agent SDK atau Remote Control

Claude Code tidak menjalankan PreModelSwitch hooks untuk switch yang dibuat sendiri, seperti automatic model fallback atau memulihkan model ketika Anda melanjutkan sesi. Perubahan itu mencapai PostModelSwitch saja.

Claude Code membandingkan matcher terhadap nama kanonik model yang sesi beralih ke, mengabaikan apa pun [1m] suffix. Alias seperti opus, ID model yang tertanggal, dan ID khusus penyedia seperti ID model Amazon Bedrock semuanya cocok dengan satu nama kanonik yang mereka selesaikan, jadi claude-opus-5 mencakup setiap ejaan Opus 5.

Ketika Claude Code tidak dapat menentukan nama kanonik untuk target, misalnya ID model kustom yang hanya LLM gateway Anda tahu, itu menjalankan setiap hook PreModelSwitch terlepas dari matcher. Hook yang memblokir harus memeriksa to_model dari input-nya daripada mengandalkan matcher saja.

Tulis matcher sebagai nama yang tepat, daftar |-separated seperti claude-opus-4-6|claude-opus-5, atau ekspresi reguler seperti .*opus.*. Contoh ini menggunakan matcher nama yang tepat dan juga memeriksa to_model dari input hook, jadi itu menolak switch ke Opus 4.6 dengan keluar dengan kode 2 dan membiarkan target lainnya melewati:

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

Untuk mengkonfirmasi hook bekerja, jalankan /model claude-opus-4-6 dari sesi yang menjalankan model berbeda. Claude Code menyimpan model saat ini dan melaporkan bahwa hook PreModelSwitch memblokir switch, dengan pesan Anda sebagai alasan.

PreModelSwitch input

Selain bidang input umum, PreModelSwitch hooks menerima bidang dalam tabel ini. Lima terakhir menjelaskan apa yang mengirim ulang percakapan ke model baru biaya, jadi hook dapat menampilkan angka itu sebelum switch terjadi.

Contoh ini menunjukkan input untuk /model opus dalam sesi yang menjalankan Sonnet 5:

{
  "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 decision control

Hooks PreModelSwitch dapat membatalkan switch, meminta pengguna untuk mengkonfirmasinya, atau membiarkannya melanjutkan. Kode keluar 2 atau decision: "block" tingkat atas membatalkan switch.

Untuk kontrol yang lebih halus, kembalikan permissionDecision dan permissionDecisionReason dalam objek hookSpecificOutput, seperti pada PreToolUse. PreModelSwitch menerima "allow", "deny", dan "ask". Itu tidak menerima "defer", updatedInput, atau additionalContext. Tabel di bawah menjelaskan kedua bidang:

Hanya /model dalam sesi interaktif dapat menampilkan prompt "ask". Di setiap permukaan lain, termasuk mode non-interaktif dengan flag -p, /config, dan permintaan set_model, Claude Code memperlakukan "ask" sebagai penolakan.

Contoh ini meminta pengguna untuk mengkonfirmasi dan mengutip jumlah token dari context_tokens:

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

Ketika beberapa PreModelSwitch hooks mengembalikan keputusan berbeda, prioritas adalah deny > ask > allow.

Claude Code menampilkan systemMessage apa pun yang dikembalikan hook Anda terlepas dari keputusan, jadi hook pelaporan biaya dapat mengembalikan {"systemMessage": "..."} dan keluar 0.

Hook PreModelSwitch yang tidak merespons sebelum timeout-nya memblokir switch. Pada PreToolUse, sebaliknya, hook command yang timed out membiarkan pemanggilan tool melanjutkan. Timeout default untuk event ini adalah 30 detik. PreModelSwitch menjalankan hooks command, http, dan mcp_tool saja, jadi default prompt dan agent tidak berlaku.

Hook yang keluar dengan kode selain 0 atau 2 dan tidak mencetak keputusan JSON tidak memblokir: Claude Code menampilkan stderr-nya dan menerapkan switch, seperti dijelaskan di bawah Other exit codes.

PostModelSwitch

Dijalankan setelah model sesi berubah. Gunakan untuk memberikan panduan khusus model kepada Claude tanpa mengedit setiap CLAUDE.md, misalnya instruksi organisasi-lebar yang berlaku pada model tertentu.

PostModelSwitch memerlukan Claude Code v2.1.251 atau lebih baru. Itu tidak dapat memblokir, karena model sudah berubah. Claude Code menjalankan PostModelSwitch hooks setelah perubahan apa pun:

• Switch yang Anda atau klien minta
• Automatic model fallback, yang mengubah model sesi
• Pengaturan seperti opusplan memasuki atau meninggalkan plan mode
• Claude Code memulihkan model ketika Anda melanjutkan sesi

Claude Code tidak menjalankan PostModelSwitch hooks ketika model dari fallback model chain melayani giliran, karena substitusi itu berlangsung satu giliran dan meninggalkan model sesi tidak berubah.

Matcher mengikuti aturan yang sama seperti PreModelSwitch: Claude Code membandingkannya terhadap nama kanonik model yang sesi beralih ke.

Contoh ini menambahkan panduan setiap kali model sesi berubah ke model Opus apa pun:

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

Untuk mengkonfirmasi hook bekerja, beralih ke model Opus dari sesi yang menjalankan model berbeda, misalnya jalankan /model opus dari sesi Sonnet, kemudian tanyakan Claude apa panduan yang dimilikinya tentang model saat ini.

PostModelSwitch input

PostModelSwitch hooks menerima bidang yang sama seperti PreModelSwitch, dengan hook_event_name diatur ke "PostModelSwitch" dan dua nilai source lebih: "auto" untuk fallback otomatis atau perubahan lain yang dibuat Claude Code sendiri, dan "resume" untuk model yang dipulihkan ketika Anda melanjutkan sesi.

requested_model adalah null ketika source adalah "auto". Ketika source adalah "resume", itu adalah pengaturan model yang disimpan Claude Code pulihkan.

PostModelSwitch decision control

Claude Code mengambil stdout plain-text hook Anda pada keluar 0, atau additionalContext dari output JSON, dan mengirimkannya ke Claude dengan permintaan setelah switch. Selain bidang output JSON yang tersedia untuk semua hooks, Anda dapat mengembalikan:

Jika hook belum selesai dalam lima detik setelah Anda mengirimkan permintaan berikutnya, Claude Code mengirimkan permintaan itu tanpa output dan melampirkannya ke permintaan berikutnya sebagai gantinya. Jika model berubah beberapa kali sebelum permintaan berikutnya, Claude Code mengirimkan hanya output untuk switch terakhir ke model target.

SessionEnd

Dijalankan ketika sesi Claude Code berakhir. Berguna untuk tugas cleanup, logging statistik sesi, atau menyimpan status sesi. Mendukung matchers untuk memfilter berdasarkan alasan keluar.

Bidang reason dalam input hook menunjukkan mengapa sesi berakhir:

SessionEnd input

Selain bidang input umum, SessionEnd hooks menerima bidang reason menunjukkan mengapa sesi berakhir. Lihat tabel reason di atas untuk semua nilai.

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

SessionEnd hooks tidak memiliki kontrol keputusan. Mereka tidak dapat memblokir penghentian sesi tetapi dapat melakukan tugas cleanup. Claude Code membuang bidang output JSON mereka, seperti systemMessage.

SessionEnd hooks memiliki timeout default 1.5 detik. Ini berlaku untuk keluar sesi, /clear, dan beralih sesi melalui /resume interaktif. Jika hook memerlukan lebih banyak waktu, atur per-hook timeout dalam konfigurasi hook. Anggaran keseluruhan secara otomatis dinaikkan ke timeout per-hook tertinggi yang dikonfigurasi dalam file pengaturan, hingga 60 detik. Timeout yang ditetapkan pada hooks yang disediakan plugin tidak menaikkan anggaran. Untuk menimpa anggaran secara eksplisit, atur variabel lingkungan CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS dalam milidetik.

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Sebelum v2.1.268, CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS menaikkan hanya anggaran keseluruhan, dan hook tanpa timeout sendiri masih dibatalkan setelah 1.5 detik.

Elicitation

Dijalankan ketika server MCP meminta input pengguna mid-task. Secara default, Claude Code menampilkan dialog interaktif untuk pengguna merespons. Hooks dapat mengintersepsi permintaan ini dan merespons secara programatis, melewati dialog sepenuhnya.

Bidang matcher mencocokkan nama server MCP.

Elicitation input

Selain bidang input umum, Elicitation hooks menerima mcp_server_name, message, dan bidang opsional mode, url, elicitation_id, dan requested_schema.

Untuk form-mode elicitation, kasus paling umum:

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

Untuk URL-mode elicitation, digunakan untuk autentikasi berbasis browser:

{
  "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 output

Untuk merespons secara programatis tanpa menampilkan dialog, kembalikan objek JSON dengan hookSpecificOutput:

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

Kode keluar 2 menolak elicitation. Claude Code tidak menampilkan pesan stderr Anda di mana pun.

Claude Code bertindak atas hookSpecificOutput dari output JSON hook Elicitation dan membuang systemMessage dan continue.

ElicitationResult

Dijalankan setelah pengguna merespons elicitation MCP. Hooks dapat mengamati, memodifikasi, atau memblokir respons sebelum dikirim kembali ke server MCP.

Bidang matcher mencocokkan nama server MCP.

ElicitationResult input

Selain bidang input umum, ElicitationResult hooks menerima mcp_server_name, action, dan bidang opsional mode, elicitation_id, dan 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 output

Untuk menimpa respons pengguna, kembalikan objek JSON dengan hookSpecificOutput:

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

Kode keluar 2 memblokir respons, mengubah tindakan efektif menjadi decline. Claude Code tidak menampilkan pesan stderr Anda di mana pun.

Claude Code bertindak atas hookSpecificOutput dari output JSON hook ElicitationResult dan membuang systemMessage dan continue.

Prompt-based hooks

Selain command, HTTP, dan MCP tool hooks, Claude Code mendukung prompt-based hooks (type: "prompt") yang menggunakan LLM untuk mengevaluasi apakah akan mengizinkan atau memblokir tindakan, dan agent hooks (type: "agent") yang spawn agentic verifier dengan akses tool. Tidak semua events mendukung setiap tipe hook.

Events yang mendukung semua lima tipe hook (command, http, mcp_tool, prompt, dan agent):

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

PermissionRequest mendukung hooks command, http, mcp_tool, dan prompt tetapi bukan hooks agent. Jika Anda mengonfigurasi agent hook pada event ini, Claude Code melewatinya dan aliran izin berlanjut tidak berubah. Untuk mengizinkan atau menolak dari hook, kembalikan objek keputusan dari command atau HTTP hook.

Events yang mendukung hooks command, http, dan mcp_tool tetapi bukan prompt atau agent:

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

SessionStart dan Setup mendukung hooks command dan mcp_tool, dan MCP tool hook fields menjelaskan kapan hooks mcp_tool mereka berjalan. Mereka tidak mendukung hooks http, prompt, atau agent.

Bagaimana prompt-based hooks bekerja

Alih-alih menjalankan perintah Bash, prompt-based hooks:

1. Mengirimkan input hook dan prompt Anda ke model Claude, Haiku secara default
2. LLM merespons dengan JSON terstruktur yang berisi keputusan
3. Claude Code memproses keputusan secara otomatis

Konfigurasi prompt hook

Atur type ke "prompt" dan sediakan string prompt alih-alih command. Gunakan placeholder $ARGUMENTS untuk menyuntikkan data JSON input hook ke dalam teks prompt Anda.

Hook Stop ini meminta LLM untuk mengevaluasi apakah semua tugas selesai sebelum mengizinkan Claude selesai:

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

Skema respons

LLM harus merespons dengan JSON yang berisi:

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

Apa yang terjadi pada ok: false tergantung pada event:

• Stop dan SubagentStop: alasan diumpankan kembali ke Claude sebagai instruksi berikutnya dan giliran berlanjut, kecuali respons juga menetapkan impossible: true, dalam hal ini Claude Code mengizinkan stop dan giliran berakhir
• PreToolUse: panggilan tool ditolak; secara default giliran berakhir dan alasan penolakan muncul dalam chat sebagai baris peringatan. Atur continueOnBlock: true untuk mengembalikan alasan ke Claude sebagai kesalahan tool sehingga dapat menyesuaikan dan melanjutkan, setara dengan permissionDecision: "deny" dari command hook. Sebelum v2.1.210, alasan penolakan dikembalikan ke Claude sebagai kesalahan tool dan giliran berlanjut
• PostToolUse: secara default giliran berakhir dan alasan muncul dalam chat sebagai baris peringatan. Atur continueOnBlock: true untuk mengirimkan alasan kembali ke Claude dan melanjutkan giliran alih-alih
• PostToolBatch, UserPromptSubmit, dan UserPromptExpansion: giliran berakhir dan alasan muncul sebagai baris peringatan. Events ini mengakhiri giliran pada decision: "block" terlepas dari continue
• PostToolUseFailure dan TaskCreated: alasan dikembalikan ke Claude sebagai kesalahan tool dan giliran berlanjut, terlepas dari continueOnBlock
• TaskCompleted: ketika terjadi karena tugas ditandai selesai selama giliran, alasan dikembalikan ke Claude sebagai kesalahan tool dan giliran berlanjut, terlepas dari continueOnBlock. Ketika terjadi karena rekan kerja berhenti, berperilaku seperti TeammateIdle dan menghentikan rekan kerja secara default
• TeammateIdle: secara default rekan kerja berhenti dan alasan muncul sebagai baris peringatan. Atur continueOnBlock: true untuk mengirimkan alasan kembali ke rekan kerja dan membiarkannya tetap bekerja alih-alih
• PermissionRequest: ok: false tidak berpengaruh. Untuk menolak persetujuan dari hook, gunakan command hook yang mengembalikan hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied: ok: false tidak berpengaruh karena penolakan sudah terjadi. Satu-satunya output yang dibaca event ini adalah hookSpecificOutput.retry, yang prompt dan agent hooks tidak dapat atur. Mereka berjalan pada event ini, tetapi output mereka diabaikan. Gunakan command hook untuk mengembalikan retry

Jika Anda memerlukan kontrol yang lebih halus pada event apa pun, gunakan command hook dengan bidang per-event yang dijelaskan dalam Decision control.

Periksa beberapa kondisi sebelum berhenti

Hook Stop ini menggunakan prompt detail untuk memeriksa tiga kondisi sebelum mengizinkan Claude berhenti. Hooks SubagentStop menggunakan format yang sama untuk mengevaluasi apakah subagent harus berhenti. Jika model mengembalikan "ok": false karena kondisi belum terpenuhi, Claude terus bekerja dengan alasan yang disediakan sebagai instruksi berikutnya:

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

Agent-based hooks

Agent-based hooks (type: "agent") seperti prompt-based hooks tetapi dengan akses tool multi-turn. Alih-alih pemanggilan LLM tunggal, hook agent spawn subagent yang dapat membaca file, mencari kode, dan memeriksa codebase untuk memverifikasi kondisi. Agent hooks mendukung events yang sama seperti prompt-based hooks, kecuali PermissionRequest.

Bagaimana agent hooks bekerja

Ketika hook agent dijalankan:

1. Claude Code spawn subagent dengan prompt Anda dan JSON input hook
2. Subagent dapat menggunakan tools seperti Read, Grep, dan Glob untuk menyelidiki
3. Setelah hingga 50 turn, subagent mengembalikan keputusan terstruktur { "ok": true/false }
4. Claude Code memungkinkan tindakan jika ok adalah true. Jika ok adalah false, Claude Code menangani blokir dengan cara yang sama seperti prompt hook dengan continueOnBlock: true pada event tersebut, seperti yang tercantum di bawah Response schema

Agent hooks berguna ketika verifikasi memerlukan memeriksa file aktual atau output test, bukan hanya mengevaluasi data input hook saja.

Konfigurasi agent hook

Atur type ke "agent" dan sediakan string prompt, menggunakan $ARGUMENTS sebagai placeholder untuk JSON input hook. Bidang konfigurasi sama seperti prompt hooks, kecuali bahwa agent hooks memiliki timeout default yang lebih lama yaitu 60 detik dan tidak ada field continueOnBlock.

Skema respons adalah { "ok": true } untuk mengizinkan atau { "ok": false, "reason": "..." } untuk memblokir. Pada ok: false, Claude Code menangani agent hook dengan cara yang sama seperti menangani prompt hook dengan continueOnBlock: true pada event yang sama; agent hooks tidak memiliki field continueOnBlock, dan tidak mendukung field impossible dari prompt hook.

Hook Stop ini memverifikasi bahwa semua unit tests lulus sebelum mengizinkan Claude selesai:

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

Jalankan hooks di latar belakang

Secara default, hooks memblokir eksekusi Claude sampai selesai. Untuk tugas yang berjalan lama seperti deployments, test suites, atau panggilan API eksternal, atur "async": true untuk menjalankan hook di latar belakang sementara Claude terus bekerja. Async hooks tidak dapat memblokir atau mengontrol perilaku Claude: bidang respons seperti decision, permissionDecision, dan continue tidak berpengaruh, karena tindakan yang akan mereka kontrol sudah selesai.

Konfigurasi async hook

Tambahkan "async": true ke konfigurasi command hook untuk menjalankannya di latar belakang tanpa memblokir Claude. Bidang ini hanya tersedia pada hooks type: "command".

Hook ini menjalankan skrip test setelah setiap pemanggilan tool Write. Claude terus bekerja segera sementara run-tests.sh dijalankan. Ketika skrip selesai, outputnya disampaikan pada turn percakapan berikutnya:

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

Setelah async hook berjalan di latar belakang, Claude Code tidak memberlakukan timeout padanya. Claude Code masih memberlakukan timeout pada hook yang Anda jalankan dengan asyncRewake.

Claude Code mengirimkan hasil async hook hanya saat sesi berjalan:

• Dalam mode non-interaktif dengan flag -p, Claude Code membunuh hook async apa pun yang masih berjalan saat teardown dan menyelesaikannya dengan outcome cancelled
• Jika pekerjaan hook Anda harus bertahan lebih lama dari sesi claude -p, mulai proses yang sepenuhnya terpisah darinya

Bagaimana async hooks dijalankan

Ketika async hook dijalankan, Claude Code memulai proses hook dan segera melanjutkan tanpa menunggu selesai. Hook menerima JSON input yang sama melalui stdin seperti hook sinkron.

Setelah proses latar belakang keluar, Claude Code mengirimkan bidang additionalContext dan systemMessage dari respons JSON hook ke Claude pada turn percakapan berikutnya. Tidak seperti systemMessage hook sinkron, tidak ada bidang yang ditampilkan kepada Anda.

Claude Code memvalidasi respons JSON tersebut terhadap output schema yang sama seperti hooks sinkron, dan menghapus bidang apa pun yang nilainya memiliki tipe yang salah, seperti systemMessage yang bukan string, alih-alih menyampaikannya. Jalankan dengan --debug untuk melihat peringatan yang menyebutkan setiap bidang yang dihapus. Sebelum v2.1.202, output JSON yang tidak terbentuk dengan baik dari async hook dapat menghancurkan sesi, dan kerusakan terulang setiap kali sesi dilanjutkan.

Notifikasi penyelesaian async hook ditekan secara default. Untuk melihatnya, aktifkan mode verbose dengan Ctrl+O atau mulai Claude Code dengan --verbose.

Jalankan tests setelah perubahan file

Hook ini memulai test suite di latar belakang setiap kali Claude menulis file, kemudian melaporkan hasil kembali ke Claude ketika tests selesai. Simpan skrip ini ke .claude/hooks/run-tests-async.sh dalam proyek Anda dan buat dapat dijalankan dengan chmod +x:

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

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

# Hanya jalankan tests untuk file sumber
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Jalankan tests dan laporkan hasil ke Claude via additionalContext
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}}'

Kemudian tambahkan konfigurasi ini ke .claude/settings.json dalam akar proyek Anda. Flag async: true memungkinkan Claude terus bekerja sementara tests dijalankan:

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

Keterbatasan

Async hooks memiliki batasan tambahan dibandingkan dengan hooks sinkron:

• Output hook disampaikan pada turn percakapan berikutnya. Jika sesi idle, respons menunggu sampai interaksi pengguna berikutnya. Pengecualian: hook asyncRewake yang keluar dengan kode 2 membangunkan Claude segera bahkan ketika sesi idle.
• Setiap eksekusi membuat proses latar belakang terpisah. Tidak ada deduplikasi di seluruh beberapa penjalankan hook async yang sama.

Pertimbangan keamanan

Penafian

Kepercayaan workspace

Claude Code memeriksa kepercayaan workspace sebelum menjalankan hook apa pun dari file pengaturan. Apa yang dianggap terpercaya tergantung pada jenis sesi:

• Sesi interaktif: Claude Code menahan hook dari setiap file pengaturan, termasuk ~/.claude/settings.json Anda sendiri, sampai Anda menerima dialog kepercayaan workspace untuk folder, atau untuk direktori induk yang kepercayaannya meluas ke dalamnya
• Sesi -p atau SDK: Claude Code tidak pernah menampilkan dialog dan memperlakukan folder sebagai terpercaya, sehingga hook yang dikomit dalam .claude/settings.json repositori berjalan di folder yang belum pernah Anda percayai

Sebelum Anda menjalankan skrip claude -p di atas repositori yang tidak Anda tulis, tinjau file pengaturan .claude/ nya, mulai dengan --bare, atau matikan hooks untuk run itu dengan --settings '{"disableAllHooks": true}'. Hook frontmatter dalam subagent proyek mengikuti aturan yang lebih ketat daripada hook file pengaturan. Apa yang berjalan sebelum Anda mempercayai folder mencantumkan setiap jenis konten repositori berdasarkan jenis sesi.

Praktik terbaik keamanan

Ingat praktik-praktik ini saat menulis hooks:

• Validasi dan sanitasi input: jangan pernah mempercayai data input secara membabi buta
• Selalu kutip variabel shell: gunakan "$VAR" bukan $VAR
• Blokir path traversal: periksa .. dalam path file
• Gunakan path absolut: tentukan path lengkap untuk skrip. Dalam bentuk exec, gunakan ${CLAUDE_PROJECT_DIR} dan path tidak perlu dikutip. Dalam bentuk shell, bungkus dengan tanda kutip ganda
• Lewati file sensitif: hindari .env, .git/, keys, dll.

Windows PowerShell tool

Di Windows, Anda dapat menjalankan hook individual dalam PowerShell dengan menetapkan "shell": "powershell" pada command hook. Claude Code auto-detects pwsh.exe, executable PowerShell 7 dan yang lebih baru, dan fallback ke powershell.exe untuk Windows PowerShell 5.1.

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

Untuk mereferensikan root proyek dari perintah bentuk shell PowerShell, tulis ${CLAUDE_PROJECT_DIR} atau $env:CLAUDE_PROJECT_DIR. Mulai dari v2.1.198, Claude Code menulis ulang placeholder ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT}, dan ${CLAUDE_PLUGIN_DATA} dalam perintah bentuk shell PowerShell ke bentuk ${env:NAME} PowerShell, baik hook didefinisikan dalam settings.json, plugin, atau skill. PowerShell kemudian menyelesaikan nilai dari lingkungan yang diekspor setelah parsing, jadi placeholder bekerja di dalam string dengan tanda kutip ganda tetapi tidak di dalam string dengan tanda kutip tunggal, di mana PowerShell tidak pernah memperluas variabel.

Sebelum v2.1.198, penulisan ulang ini hanya berlaku untuk plugin hooks. Pada versi yang lebih awal, hook settings.json memerlukan bentuk $env: atau exec form, di mana ${CLAUDE_PROJECT_DIR} diganti di setiap elemen args terlepas dari di mana hook didefinisikan.

Jangan tulis ejaan bare $CLAUDE_PROJECT_DIR dalam hook PowerShell. PowerShell menguraikannya sebagai variabel lokal yang tidak terdefinisi dan menyelesaikannya ke $null, yang meninggalkan jalur skrip tanpa awalan root proyeknya. Claude Code tidak menulis ulang bentuk itu; sebaliknya, ia mencatat peringatan dalam debug log.

Contoh di bawah menunjukkan hook settings.json yang menjalankan skrip proyek dengan bentuk $env:, yang bekerja di setiap versi:

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

Debug hooks

Detail eksekusi hook ditulis ke file debug log. Mulai Claude Code dengan claude --debug-file <path> untuk menulis log ke lokasi yang diketahui, atau jalankan claude --debug dan baca log di ~/.claude/debug/<session-id>.txt. Flag --debug tidak mencetak ke terminal.

Sebagai contoh, hook PostToolUse pada Write yang perintahnya mencetak hook-ran menghasilkan entri seperti:

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"

Untuk detail pencocokan hook yang lebih granular, atur CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose untuk melihat baris log tambahan seperti jumlah matcher hook dan pencocokan query.

Untuk troubleshooting masalah umum seperti hooks tidak dijalankan, Stop hooks yang terus memblokir, atau kesalahan konfigurasi, lihat Limitations and troubleshooting dalam panduan. Untuk panduan diagnostik yang lebih luas mencakup /context, /doctor, dan precedence pengaturan, lihat Debug your config.