Referensi hooks
Halaman ini menyediakan dokumentasi referensi untuk mengimplementasikan hooks di Claude Code.
Untuk panduan quickstart dengan contoh, lihat Memulai dengan hooks Claude Code.
Konfigurasi
Hooks Claude Code dikonfigurasi dalam file pengaturan Anda:
~/.claude/settings.json
- Pengaturan pengguna.claude/settings.json
- Pengaturan proyek.claude/settings.local.json
- Pengaturan proyek lokal (tidak di-commit)- Pengaturan kebijakan yang dikelola enterprise
Struktur
Hooks diorganisir berdasarkan matcher, di mana setiap matcher dapat memiliki beberapa hooks:
- matcher: Pola untuk mencocokkan nama tool, case-sensitive (hanya berlaku untuk
PreToolUse
danPostToolUse
)- String sederhana cocok persis:
Write
hanya cocok dengan tool Write - Mendukung regex:
Edit|Write
atauNotebook.*
- Gunakan
*
untuk mencocokkan semua tool. Anda juga dapat menggunakan string kosong (""
) atau membiarkanmatcher
kosong.
- String sederhana cocok persis:
- hooks: Array perintah untuk dieksekusi ketika pola cocok
type
: Saat ini hanya"command"
yang didukungcommand
: Perintah bash untuk dieksekusi (dapat menggunakan variabel lingkungan$CLAUDE_PROJECT_DIR
)timeout
: (Opsional) Berapa lama perintah harus berjalan, dalam detik, sebelum membatalkan perintah spesifik tersebut.
Untuk event seperti UserPromptSubmit
, Notification
, Stop
, dan SubagentStop
yang tidak menggunakan matcher, Anda dapat menghilangkan field matcher:
Script Hook Spesifik Proyek
Anda dapat menggunakan variabel lingkungan CLAUDE_PROJECT_DIR
(hanya tersedia ketika
Claude Code menjalankan perintah hook) untuk mereferensikan script yang disimpan dalam proyek Anda,
memastikan mereka bekerja terlepas dari direktori saat ini Claude:
Event Hook
PreToolUse
Berjalan setelah Claude membuat parameter tool dan sebelum memproses panggilan tool.
Matcher umum:
Task
- Tugas subagent (lihat dokumentasi subagent)Bash
- Perintah shellGlob
- Pencocokan pola fileGrep
- Pencarian kontenRead
- Pembacaan fileEdit
,MultiEdit
- Pengeditan fileWrite
- Penulisan fileWebFetch
,WebSearch
- Operasi web
PostToolUse
Berjalan segera setelah tool selesai dengan sukses.
Mengenali nilai matcher yang sama seperti PreToolUse.
Notification
Berjalan ketika Claude Code mengirim notifikasi. Notifikasi dikirim ketika:
- Claude memerlukan izin Anda untuk menggunakan tool. Contoh: “Claude needs your permission to use Bash”
- Input prompt telah idle selama setidaknya 60 detik. “Claude is waiting for your input”
UserPromptSubmit
Berjalan ketika pengguna mengirimkan prompt, sebelum Claude memprosesnya. Ini memungkinkan Anda untuk menambahkan konteks tambahan berdasarkan prompt/percakapan, memvalidasi prompt, atau memblokir jenis prompt tertentu.
Stop
Berjalan ketika agen utama Claude Code telah selesai merespons. Tidak berjalan jika penghentian terjadi karena interupsi pengguna.
SubagentStop
Berjalan ketika sub agent Claude Code (panggilan tool Task) telah selesai merespons.
PreCompact
Berjalan sebelum Claude Code akan menjalankan operasi compact.
Matcher:
manual
- Dipanggil dari/compact
auto
- Dipanggil dari auto-compact (karena context window penuh)
Input Hook
Hook menerima data JSON melalui stdin yang berisi informasi sesi dan data spesifik event:
Input PreToolUse
Skema yang tepat untuk tool_input
tergantung pada tool.
Input PostToolUse
Skema yang tepat untuk tool_input
dan tool_response
tergantung pada tool.
Input Notification
Input UserPromptSubmit
Input Stop dan SubagentStop
stop_hook_active
adalah true ketika Claude Code sudah melanjutkan sebagai hasil dari
stop hook. Periksa nilai ini atau proses transkrip untuk mencegah Claude Code
berjalan tanpa batas.
Input PreCompact
Untuk manual
, custom_instructions
berasal dari apa yang pengguna masukkan ke
/compact
. Untuk auto
, custom_instructions
kosong.
Output Hook
Ada dua cara untuk hook mengembalikan output kembali ke Claude Code. Output mengkomunikasikan apakah akan memblokir dan feedback apa pun yang harus ditampilkan kepada Claude dan pengguna.
Sederhana: Exit Code
Hook mengkomunikasikan status melalui exit code, stdout, dan stderr:
- Exit code 0: Sukses.
stdout
ditampilkan kepada pengguna dalam mode transkrip (CTRL-R), kecuali untukUserPromptSubmit
, di mana stdout ditambahkan ke konteks. - Exit code 2: Error yang memblokir.
stderr
diberikan kembali ke Claude untuk diproses secara otomatis. Lihat perilaku per-hook-event di bawah. - Exit code lainnya: Error yang tidak memblokir.
stderr
ditampilkan kepada pengguna dan eksekusi berlanjut.
Pengingat: Claude Code tidak melihat stdout jika exit code adalah 0, kecuali untuk
hook UserPromptSubmit
di mana stdout diinjeksi sebagai konteks.
Perilaku Exit Code 2
Event Hook | Perilaku |
---|---|
PreToolUse | Memblokir panggilan tool, menampilkan stderr ke Claude |
PostToolUse | Menampilkan stderr ke Claude (tool sudah berjalan) |
Notification | N/A, menampilkan stderr hanya ke pengguna |
UserPromptSubmit | Memblokir pemrosesan prompt, menghapus prompt, menampilkan stderr hanya ke pengguna |
Stop | Memblokir penghentian, menampilkan stderr ke Claude |
SubagentStop | Memblokir penghentian, menampilkan stderr ke subagent Claude |
PreCompact | N/A, menampilkan stderr hanya ke pengguna |
Lanjutan: Output JSON
Hook dapat mengembalikan JSON terstruktur dalam stdout
untuk kontrol yang lebih canggih:
Field JSON Umum
Semua jenis hook dapat menyertakan field opsional ini:
Jika continue
adalah false, Claude berhenti memproses setelah hook berjalan.
- Untuk
PreToolUse
, ini berbeda dari"permissionDecision": "deny"
, yang hanya memblokir panggilan tool spesifik dan memberikan feedback otomatis ke Claude. - Untuk
PostToolUse
, ini berbeda dari"decision": "block"
, yang memberikan feedback otomatis ke Claude. - Untuk
UserPromptSubmit
, ini mencegah prompt diproses. - Untuk
Stop
danSubagentStop
, ini mengambil prioritas atas output"decision": "block"
apa pun. - Dalam semua kasus,
"continue" = false
mengambil prioritas atas output"decision": "block"
apa pun.
stopReason
menyertai continue
dengan alasan yang ditampilkan kepada pengguna, tidak ditampilkan
kepada Claude.
Kontrol Keputusan PreToolUse
Hook PreToolUse
dapat mengontrol apakah panggilan tool berlanjut.
"allow"
melewati sistem izin.permissionDecisionReason
ditampilkan kepada pengguna tetapi tidak kepada Claude. (Nilai"approve"
yang deprecated +reason
memiliki perilaku yang sama.)"deny"
mencegah panggilan tool dieksekusi.permissionDecisionReason
ditampilkan kepada Claude. (Nilai"block"
+reason
memiliki perilaku yang sama.)"ask"
meminta pengguna untuk mengonfirmasi panggilan tool di UI.permissionDecisionReason
ditampilkan kepada pengguna tetapi tidak kepada Claude.
Kontrol Keputusan PostToolUse
Hook PostToolUse
dapat mengontrol apakah panggilan tool berlanjut.
"block"
secara otomatis meminta Claude denganreason
.undefined
tidak melakukan apa-apa.reason
diabaikan.
Kontrol Keputusan UserPromptSubmit
Hook UserPromptSubmit
dapat mengontrol apakah prompt pengguna diproses.
"block"
mencegah prompt diproses. Prompt yang dikirimkan dihapus dari konteks."reason"
ditampilkan kepada pengguna tetapi tidak ditambahkan ke konteks.undefined
memungkinkan prompt berlanjut secara normal."reason"
diabaikan."hookSpecificOutput.additionalContext"
menambahkan string ke konteks jika tidak diblokir.
Kontrol Keputusan Stop
/SubagentStop
Hook Stop
dan SubagentStop
dapat mengontrol apakah Claude harus melanjutkan.
"block"
mencegah Claude berhenti. Anda harus mengisireason
untuk Claude mengetahui cara melanjutkan.undefined
memungkinkan Claude berhenti.reason
diabaikan.
Contoh Exit Code: Validasi Perintah Bash
Contoh Output JSON: UserPromptSubmit untuk Menambah Konteks dan Validasi
Untuk hook UserPromptSubmit
, Anda dapat menginjeksi konteks menggunakan salah satu metode:
- Exit code 0 dengan stdout: Claude melihat konteks (kasus khusus untuk
UserPromptSubmit
) - Output JSON: Memberikan kontrol lebih atas perilaku
Contoh Output JSON: PreToolUse dengan Persetujuan
Bekerja dengan Tool MCP
Hook Claude Code bekerja dengan mulus dengan tool Model Context Protocol (MCP). Ketika server MCP menyediakan tool, mereka muncul dengan pola penamaan khusus yang dapat Anda cocokkan dalam hook Anda.
Penamaan Tool MCP
Tool MCP mengikuti pola mcp__<server>__<tool>
, misalnya:
mcp__memory__create_entities
- Tool create entities server Memorymcp__filesystem__read_file
- Tool read file server Filesystemmcp__github__search_repositories
- Tool search server GitHub
Mengkonfigurasi Hook untuk Tool MCP
Anda dapat menargetkan tool MCP spesifik atau seluruh server MCP:
Contoh
Untuk contoh praktis termasuk format kode, notifikasi, dan perlindungan file, lihat Contoh Lainnya dalam panduan memulai.
Pertimbangan Keamanan
Disclaimer
GUNAKAN DENGAN RISIKO SENDIRI: Hook Claude Code mengeksekusi perintah shell arbitrer pada sistem Anda secara otomatis. Dengan menggunakan hook, Anda mengakui bahwa:
- Anda sepenuhnya bertanggung jawab atas perintah yang Anda konfigurasi
- Hook dapat memodifikasi, menghapus, atau mengakses file apa pun yang dapat diakses akun pengguna Anda
- Hook yang berbahaya atau ditulis dengan buruk dapat menyebabkan kehilangan data atau kerusakan sistem
- Anthropic tidak memberikan jaminan dan tidak bertanggung jawab atas kerusakan apa pun yang diakibatkan oleh penggunaan hook
- Anda harus menguji hook secara menyeluruh dalam lingkungan yang aman sebelum penggunaan produksi
Selalu tinjau dan pahami perintah hook apa pun sebelum menambahkannya ke konfigurasi Anda.
Praktik Terbaik Keamanan
Berikut adalah beberapa praktik kunci untuk menulis hook yang lebih aman:
- 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 script (gunakan
$CLAUDE_PROJECT_DIR
untuk path proyek) - Lewati file sensitif - Hindari
.env
,.git/
, kunci, dll.
Keamanan Konfigurasi
Edit langsung pada hook dalam file pengaturan tidak berlaku segera. Claude Code:
- Mengambil snapshot hook saat startup
- Menggunakan snapshot ini sepanjang sesi
- Memperingatkan jika hook dimodifikasi secara eksternal
- Memerlukan tinjauan dalam menu
/hooks
agar perubahan berlaku
Ini mencegah modifikasi hook berbahaya mempengaruhi sesi Anda saat ini.
Detail Eksekusi Hook
- Timeout: Batas eksekusi 60 detik secara default, dapat dikonfigurasi per perintah.
- Timeout untuk perintah individual tidak mempengaruhi perintah lainnya.
- Paralelisasi: Semua hook yang cocok berjalan secara paralel
- Lingkungan: Berjalan dalam direktori saat ini dengan lingkungan Claude Code
- Variabel lingkungan
CLAUDE_PROJECT_DIR
tersedia dan berisi path absolut ke direktori root proyek
- Variabel lingkungan
- Input: JSON melalui stdin
- Output:
- PreToolUse/PostToolUse/Stop: Progress ditampilkan dalam transkrip (Ctrl-R)
- Notification: Dicatat hanya ke debug (
--debug
)
Debugging
Pemecahan Masalah Dasar
Jika hook Anda tidak bekerja:
- Periksa konfigurasi - Jalankan
/hooks
untuk melihat apakah hook Anda terdaftar - Verifikasi sintaks - Pastikan pengaturan JSON Anda valid
- Uji perintah - Jalankan perintah hook secara manual terlebih dahulu
- Periksa izin - Pastikan script dapat dieksekusi
- Tinjau log - Gunakan
claude --debug
untuk melihat detail eksekusi hook
Masalah umum:
- Tanda kutip tidak di-escape - Gunakan
\"
di dalam string JSON - Matcher salah - Periksa nama tool cocok persis (case-sensitive)
- Perintah tidak ditemukan - Gunakan path lengkap untuk script
Debugging Lanjutan
Untuk masalah hook yang kompleks:
- Inspeksi eksekusi hook - Gunakan
claude --debug
untuk melihat eksekusi hook yang detail - Validasi skema JSON - Uji input/output hook dengan tool eksternal
- Periksa variabel lingkungan - Verifikasi lingkungan Claude Code benar
- Uji kasus edge - Coba hook dengan path file atau input yang tidak biasa
- Monitor sumber daya sistem - Periksa kelelahan sumber daya selama eksekusi hook
- Gunakan logging terstruktur - Implementasikan logging dalam script hook Anda
Contoh Output Debug
Gunakan claude --debug
untuk melihat detail eksekusi hook:
Pesan progress muncul dalam mode transkrip (Ctrl-R) menampilkan:
- Hook mana yang berjalan
- Perintah yang dieksekusi
- Status sukses/gagal
- Pesan output atau error