on(eventName, handler).
Bangun mod pertama Anda sebelum Anda mulai di sini. Untuk setiap peristiwa dan bidangnya yang tepat, lihat referensi atau baca tipe untuk build Anda.
Bagaimana hook menangani peristiwa
Hook duduk di antara peristiwa dan apa yang akan dilakukan Claude Code tentangnya, sehingga dapat mengamati peristiwa, menulis ulangnya, atau menjawabnya sendiri. Hook menerima tiga argumen: mods API sebagai$, peristiwa sebagai e, dan penanganan berikutnya sebagai next. Penanganan untuk peristiwa membentuk rantai middleware. next(e) memanggil penanganan berikutnya, yang merupakan hook mod lain atau, di akhir rantai, perilaku Claude Code sendiri, dan diselesaikan dengan hasilnya. Apa yang dilakukan hook Anda dengan next menentukan mana dari ketiga hal itu yang dilakukannya.
Amati peristiwa
Untuk mengamati peristiwa tanpa mengubahnya, lakukan pekerjaan Anda dan kembalikannext(e). Hook ini mencatat setiap alat yang akan digunakan Claude:
โ my-mod: Claude is about to use Bash muncul dalam transkrip, di mana my-mod adalah nama plugin Anda. Alat berjalan seperti yang akan terjadi tanpa mod.
Untuk bertindak setelah peristiwa, await next(e), lakukan pekerjaan Anda, dan kembalikan hasilnya. Hook ini mencatat setiap alat setelah dijalankan:
next(e).
Tulis ulang peristiwa
Untuk mengubah apa yang Claude Code bertindak, seperti teks prompt, panggilnext dengan salinan peristiwa yang dimodifikasi. Peristiwa itu sendiri tidak dapat diubah: peristiwa itu dibekukan di setiap kedalaman, dan penugasan ke bidang melempar. Hook ini memangkas setiap prompt sebelum dikirim:
await next(e), kemudian kembalikan salinan hasil dengan bidang yang diganti.
Jawab peristiwa
Untuk menangani peristiwa sendiri, kembalikan hasil tanpa memanggilnext. Itu memotong rantai, sehingga mod berikutnya dan perilaku Claude Code sendiri tidak berjalan. Hook ini menolak setiap perintah Bash:
deny sebagai hasil alat. Setiap peristiwa memiliki bentuk hasil sendiri, yang referensi peristiwa daftarkan.
Saring peristiwa mana yang ditangani hook
Untuk menjalankan hook hanya untuk beberapa peristiwa, teruskan filter sebagai argumen kedua keon. Claude Code memanggil filter sebagai matcher. Ini adalah objek yang bidangnya dibandingkan dengan peristiwa, dan hook hanya berjalan ketika setiap bidang cocok. Bidang dapat berupa nilai, array nilai yang diizinkan, atau ekspresi reguler.
Setiap baris dalam contoh ini mendaftarkan fungsi yang sama, hook, untuk set panggilan alat yang lebih sempit:
hook berjalan sekali untuk panggilan Bash, Edit, atau Write, dan sekali untuk panggilan ke alat yang namanya dimulai dengan mcp__github__. Panggilan ke alat lain apa pun, seperti Read, tidak cocok dengan ketiga hal itu, jadi hook tidak berjalan untuk itu.
Nama peristiwa dapat berupa wildcard. 'classic.*' cocok dengan setiap peristiwa hook pengaturan. '*' cocok dengan setiap peristiwa kecuali peristiwa telemetri, yang memerlukan namanya sendiri dan filter { to: 'collector' }.
Daftarkan setiap peristiwa sekali per matcher. Jika Anda memanggil on dua kali untuk session.start tanpa matcher, modul gagal dimuat dengan on("session.start") is registered twice without a matcher. Masukkan semua yang dilakukan mod Anda saat memulai sesi dalam satu hook.
Hook gambar dan kontrol mod lain
Untuk melakukan hook pada kontrol, panel, atau baris di atas prompt milik mod lain, teruskan matcher denganplugin. Gunakan nama mod tanpa marketplace-nya, seperti dalam { plugin: 'other-mod' }, atau { plugin: '*' } untuk setiap mod. Tanpa plugin, hook pada ui.press, ui.input, ui.select, atau ui.focus tidak berjalan untuk kontrol mod lain, dan hook ui.render melewati panel mereka dan baris mereka di atas prompt.
Hook pada wildcard tanpa matcher, seperti on('*', hook) atau on('ui.*', hook), tetap berjalan untuk setiap mod. Wildcard dengan matcher juga memerlukan plugin.
{ plugin: '*' } memerlukan Claude Code v2.1.323 atau yang lebih baru. Sebelum v2.1.323, hook tanpa plugin berjalan untuk setiap mod, dan hook dengan { plugin: '*' } tidak berjalan. Untuk mencocokkan setiap mod di kedua versi, gunakan { plugin: /./ } pada ui.press, ui.input, dan ui.select. Untuk ui.focus dan ui.render, gunakan on('ui.*', hook) dan periksa nama peristiwa di next.event, seperti dalam if (next.event !== 'ui.focus') return next(e).Hook apa yang dilakukan Claude
Tangani peristiwa ini untuk melihat atau mengubah panggilan tool, prompt, giliran, atau pembacaan pengaturan saat terjadi. Untuk setiap peristiwa dan apa yang dapat dikembalikan hook, lihat referensi peristiwa.Lindungi atau ubah panggilan tool
Hooktool.call melihat setiap tool yang akan digunakan Claude, sehingga dapat menolak panggilan, mengubah argumennya, atau membiarkannya lewat. tool.call diaktifkan ketika Claude Code akan menjalankan tool, termasuk panggilan yang dibuat subagent dan panggilan ke tool MCP. e.tool adalah nama tool dan argumen tool adalah bidang e, seperti e.command untuk Bash. Ketika Anda memanggil next(e), Claude Code menjalankan pemeriksaan izin dan kemudian tool tersebut.
Hook ini menolak perintah Bash yang melakukan force-push, dan memberi tahu Claude alasannya:
git push --force, perintah tidak berjalan dan tidak ada permintaan izin yang muncul, karena hook tidak pernah memanggil next. Claude membaca teks deny sebagai hasil tool, jadi tulislah sebagai instruksi yang dapat ditindaklanjuti Claude. Setiap perintah Bash lain berjalan seperti yang akan terjadi tanpa mod.
Jika hook ini melempar error atau melampaui batas waktu, Claude Code melewatinya dan perintah berlanjut seperti yang akan terjadi tanpa mod. Untuk menolak perintah sebagai gantinya, tambahkan handler .catch ke hook tersebut.
Untuk bertindak setelah tool berjalan, await next(e), lakukan pekerjaan Anda, dan kembalikan apa yang diberikan next. Hook ini mencatat setiap file .mdx yang diubah Claude, dengan $.ui.log, yang menambahkan baris redup ke transkrip yang tidak dibaca Claude:
.mdx, baris redup dalam transkrip menyebutkan nama file tersebut. Tidak ada yang dicatat untuk jenis file lain, atau untuk panggilan yang ditolak atau gagal. Pandangan Claude tentang panggilan tidak berubah, karena hook mengembalikan hasil yang diterimanya.
Hook Anda juga dapat mengubah panggilan, mencobanya ulang, menjawabnya sendiri, atau menahan hasilnya:
- Ubah panggilan: teruskan argumen yang diubah ke
next. - Coba ulang panggilan: panggil
next(e)lagi. Hook yang melihatisErrorpada hasil pertama dapat menjalankan tool untuk kedua kalinya dan mengembalikan hasil tersebut. - Jawab panggilan sendiri: kembalikan objek dengan bidang
result, tanpa memanggilnext, dan untuk tool bawaan, berikanresultbentuk yang dimiliki hasil tool itu sendiri dalam tipe untuk build Anda. Tidak ada permintaan izin yang muncul dan tool tidak berjalan, jadi hasil yang Anda kembalikan adalah satu-satunya yang diketahui Claude tentang apa yang terjadi. - Tahan hasil dari Claude: kembalikan
{ deny: reason }setelahawait next(e). Claude membaca alasan Anda sebagai pengganti apa yang dikembalikannext. Ketika tool sudah berjalan, deny menahan hasilnya dari Claude dan tidak membatalkan apa pun yang telah dilakukan tool. Ketika tool berjalan dan berhasil, alasan tersebut mengikuti catatan sepertiBash ran, and a plugin withheld its result:.
tool.call mod mana pun. Ketika hook terkelola memblokir panggilan, tidak ada hook tool.call mod yang berjalan untuk panggilan tersebut.
Tahan panggilan tool sampai pengguna memutuskan
Hook dapat menjeda panggilan tool dan menanyakan kepada pengguna apa yang harus dilakukan sebelum melanjutkan. Hooktool.call dapat melakukan await sebelum memanggil next atau mengembalikan nilai, dan panggilan tool tetap tertunda sampai saat itu. Untuk mengajukan pertanyaan kepada pengguna, panggil $.ui.ask. Ini menampilkan pertanyaan Anda di atas daftar bernomor opsi Anda, dalam dialog yang digunakan Claude untuk menanyakan sesuatu kepada Anda, dan diselesaikan dengan label yang dipilih pengguna. Setelah opsi Anda, dialog menambahkan baris untuk mengetik jawaban berbeda dan baris Chat about this.
Pola RISKY dalam contoh ini cocok dengan rm -r, rm -rf, git reset --hard, dan git push dengan --force, dan melewatkan penulisan lain seperti git push -f. Modul ini bertanya sebelum menjalankan perintah Bash yang cocok dengan pola tersebut:
rm -rf build, pertanyaan muncul dengan perintah tersebut di dalamnya, dan perintah menunggu jawaban:
- Pengguna memilih Run it: hook memanggil
next(e), dan pemeriksaan izin biasa tetap berjalan setelahnya - Pengguna memilih Refuse: perintah tidak berjalan, dan Claude membaca teks
deny - Pengguna mengetik jawaban:
$.ui.askdiselesaikan dengan teks yang diketik. Hook membandingkannya denganRun it, jadi teks lain apa pun menolak perintah. - Tidak ada yang menjawab:
$.ui.askmenolak ketika pengguna menutup pertanyaan atau memilih Chat about this, dan dalam eksekusiclaude -p, sehingga blokcatchmembiarkan jawaban tetapRefuse
$.ui.ask, karena waktu tersebut tidak dihitung terhadap batas waktu hook. Waktu yang dihabiskan untuk menunggu promise Anda sendiri tetap dihitung.
Claude Code melewati hook yang melampaui batas waktu, sehingga perintah yang ditahan akan berjalan. Untuk menolaknya sebagai gantinya, rangkaikan handler .catch ke registrasi yang dikembalikan on. Handler tersebut terpisah dari blok catch di dalam hook.
Setujui atau tolak panggilan tool sebelum pengguna ditanya
Untuk memutuskan apakah panggilan tool boleh berjalan, tanganitool.check, peristiwa tempat Claude Code membuat keputusan tersebut.
Untuk perintah atau path yang tetap, gunakan aturan izin seperti Bash(npm test), yang tidak memerlukan kode. Tangani tool.check ketika keputusan bergantung pada apa yang berlaku pada saat itu, seperti branch Git saat ini atau nilai yang dicatat oleh hook lain.
- Apa yang dikembalikan: untuk memutuskan panggilan sendiri, kembalikan objek Anda sendiri, seperti
{ decision: 'allow' }atau{ decision: 'deny', reason }. Untuk membiarkan keputusan apa adanya, kembalikan apa yang diberikanawait next(e)kepada Anda. - Apa yang diberikan
await next(e): keputusan Claude Code sendiri, sebagai objek yangdecision-nya adalahallow,ask, ataudeny. Tidak ada permintaan izin yang muncul selamanext(e)berjalan. - Argumen:
e.inputberisi argumen tool, seperticommanduntuk Bash - Kapan
tool.checkdiaktifkan: setelah hookPreToolUseberjalan, dan sebelum permintaan izin, pengklasifikasi auto mode, atau hookPermissionRequest
git push saat branch saat ini adalah main:
git push di main dan meneruskan setiap panggilan lain:
- Di
main: hook mengembalikandeny, bahkan ketika suatu aturan mengizinkangit push - Di branch lain, dan untuk perintah lain: panggilan mendapatkan keputusan yang akan didapatnya tanpa mod
- Hook melempar error atau melampaui batas waktu: panggilan juga mendapatkan keputusan yang akan didapatnya tanpa mod. Untuk menolak panggilan sebagai gantinya, tambahkan handler
.catchyang mengembalikan{ decision: 'deny', reason: 'the reason' }.
main bagi semua orang, lindungi branch tersebut di host Git Anda.
Hook
tool.check juga dapat mengembalikan allow atau ask. Dalam plan mode, untuk panggilan yang tidak read-only, seperti pengeditan file, hook Anda dapat memperketat keputusan yang dikembalikan next(e) tetapi tidak dapat melonggarkannya. Untuk aturan izin dan keputusan hook PreToolUse yang tidak dapat digantikan oleh allow dari hook Anda, lihat Perluas izin dengan hook.Periksa apakah panggilan tool bersifat read-only
Dalam hooktool.check, e.isReadOnly bernilai true ketika tool melaporkan panggilan tersebut sebagai read-only. Jika tidak, bidang ini tidak ada, bukan false. e.isReadOnly memerlukan Claude Code v2.1.304 atau yang lebih baru.
Beberapa tool, seperti Read, Grep, Glob, dan WebSearch, melaporkan setiap panggilan sebagai read-only. Bash dan tool MCP melaporkan panggilan sebagai read-only dalam kasus berikut:
- Bash: perintah lolos pemeriksaan perintah read-only bawaan Claude Code
- Tool MCP: server menetapkan anotasi
readOnlyHinttool tersebut ketrue
ask untuk setiap panggilan mcp__github__ yang tidak read-only dan belum ditolak:
Filter hook tool.check berdasarkan apakah panggilan bersifat read-only
Untuk membatasi panggilan mana yang ditangani hook Anda berdasarkan e.isReadOnly, gunakan matcher untuk panggilan read-only dan badan hook untuk sisanya:
- Hanya panggilan read-only: tambahkan
isReadOnly: trueke matcher, seperti dalamon('tool.check', { tool: 'Bash', isReadOnly: true }, hook) - Panggilan yang tidak read-only: uji
e.isReadOnlydi badan hook, seperti yang dilakukan contohmcp__github__. Jika Anda menaruhisReadOnly: falsedalam matcher, hook Anda tidak pernah berjalan.
Tulis ulang atau tambahkan ke prompt
Hookprompt.submit melihat setiap prompt sebelum giliran dimulai, sehingga dapat menulis ulang teks atau menambahkan sesuatu padanya. e.text adalah apa yang diketik.
Hook ini menambahkan nama branch saat ini untuk Claude setiap kali prompt menyebutkan pull request:
open a PR for this change, pesan Anda terlihat sama dalam transkrip, dan Claude juga membaca baris seperti Current branch: feature/auth setelahnya. Prompt yang tidak menyebutkan pull request diteruskan tanpa perubahan, dan git tidak berjalan.
Untuk menghentikan prompt, kembalikan { drop: 'the reason' } tanpa memanggil next. Teks tersebut kembali ke input prompt pengguna, dan mereka melihat Prompt dropped by a hook: diikuti alasan Anda, jadi tujukan alasan tersebut kepada mereka. Prompt tetap diteruskan dalam kasus berikut:
- Hook Anda mengembalikan
dropsetelah panggilannext(e)-nya meloloskan prompt: giliran tetap berjalan, dan hook gagal dengan pesan yang menyertakana drop after its next() was answered - Hook Anda melempar error atau melampaui batas waktu: Claude Code melewatinya dan mengirim prompt. Tambahkan handler
.catchagar kegagalan tidak mengirim prompt yang seharusnya dihentikan oleh hook.
prompt.section untuk setiap bagian system prompt, prompt.context untuk konteks yang dikirim dengan pesan pertama, dan skill.prompt untuk teks skill. Untuk mengubah suatu bagian setelah percakapan dimulai, lihat Kirim bagian system prompt atau deskripsi tool yang diubah. Dalam hook skill.prompt, Anda juga dapat membaca dari plugin atau file mana skill tersebut berasal.
Ikuti giliran
Giliran adalah semua yang dilakukan Claude sebagai jawaban atas satu prompt. Tanganiturn.start, turn.step, dan turn.complete untuk mengikutinya:
Tulis hook
turn.step sebagai generator asinkron, karena peristiwa ini mengalirkan data secara streaming. yield* next(e) meneruskan respons saat dialirkan dan menghasilkan hasil akhir. Hook ini mencatat berapa banyak dari setiap permintaan yang dilayani Claude API dari cache prompt:
result.usage menyimpan hitungan token yang dilaporkan Claude API untuk permintaan, ditambah model yang menjawab: input_tokens, output_tokens, cache_read_input_tokens, dan cache_creation_input_tokens. Hook juga berjalan untuk permintaan subagent, jadi periksa e.agentId ketika Anda hanya menginginkan percakapan utama.
Untuk melihat panggilan tool yang dijalankan sendiri oleh API selama permintaan, seperti panggilan ke tool advisor, baca result.serverToolUses. Claude Code tidak menjalankan panggilan ini, sehingga tidak ada hook tool.call atau tool.check yang diaktifkan untuk panggilan tersebut. Bidang ini tidak ada ketika respons tidak memiliki panggilan semacam itu, dan memerlukan Claude Code v2.1.290 atau yang lebih baru.
Kirim permintaan ke model yang berbeda
Jika permintaanturn.step gagal dengan error model ketika model adalah alias seperti haiku, perbarui ke Claude Code v2.1.309 atau yang lebih baru, atau gunakan id model lengkap. Sebelum v2.1.309, alias dikirim apa adanya.
Untuk mengirim permintaan ke model yang berbeda, teruskan ke next peristiwa dengan model yang diubah, seperti dalam yield* next({ ...e, model: 'haiku' }).
Ubah atau tolak pembacaan pengaturan
Gunakan hooksettings.read untuk mengubah atau menolak pembacaan pengaturan, baik pembacaan oleh mod maupun pembacaan oleh Claude Code sendiri:
- Pembacaan oleh mod: mod memanggil
$.settings.read. - Pembacaan oleh Claude Code sendiri: hook Anda pertama kali berjalan ketika Claude Code menggabungkan pengaturan sesi, setelah mod sesi dimuat. Hook Anda berjalan lagi ketika pengaturan atau plugin yang dimuat berubah.
- Penjaga bawaan: di tempat penjaga bawaan dimuat, penjaga tersebut dapat melewati hook ini dalam mod yang Anda instal atau muat dengan
--plugin-dir. Untuk memeriksanya, carisettings.read bypassed by cc-plugin-sec-defaultdi log debug. Jika baris dengan teks tersebut menyebutkan mod Anda, minta administrator organisasi Anda untuk menginstal mod tersebut sebagai salah satu mod organisasi. - Versi: peristiwa yang diaktifkan pada pembacaan Claude Code sendiri, dan bidang
e.layers, memerlukan Claude Code v2.1.304 atau yang lebih baru.
Apa yang diterima hook settings.read
Dalam
e.layers, plugin berisi pengaturan yang disediakan plugin yang diaktifkan, dan hanya merupakan nama lapisan, bukan source yang dapat Anda teruskan ke $.settings.read. flag berisi pengaturan yang diteruskan dengan --settings, dan policy berisi pengaturan terkelola.
Bedakan pembacaan Claude Code sendiri dari pembacaan oleh mod
Periksanext.origin:
- Pembacaan oleh Claude Code sendiri:
{ plugin: 'engine', tier: 'core' } - Pembacaan oleh mod:
pluginadalah nama mod yang memanggil
Apa yang dapat dikembalikan hook settings.read
Kembalikan hasil next(e) tanpa perubahan untuk membiarkan pembacaan apa adanya, atau kembalikan salah satu dari berikut:
Pada pembacaan Claude Code sendiri, susun
{ value } Anda dari value milik next(e), karena kunci yang Anda hilangkan menjadi tidak ditetapkan. Di tempat Claude Code membaca kunci seperti env dari setiap sumber secara terpisah, mengubahnya dalam value Anda tidak berpengaruh.
Apa yang diberikan next(e) kepada hook settings.read
next(e) diselesaikan dengan { value } atau dengan { deny }:
{ value }:valueadalah pengaturan gabungan, atau pengaturan satu sumber ketikae.sourceditetapkan. Jika hook yang berjalan setelah hook Anda mengembalikan{ value }miliknya sendiri, Anda mendapatkanvaluedari hook tersebut sebagai gantinya.{ deny }: hook yang berjalan setelah hook Anda menolak pembacaan. Kembalikan{ deny }tersebut tanpa perubahan.
Ubah satu pengaturan dari hook settings.read
Pertama, periksa mod mana yang mendapatkan peristiwa ini, dan sejak versi berapa.
Untuk mengubah satu kunci, sebarkan value dari next(e) dan tetapkan kunci tersebut, seperti yang dilakukan hook ini dengan spinnerTipsEnabled. Hook tidak memeriksa next.origin, sehingga hook mengubah kunci tersebut baik pada pembacaan Claude Code sendiri maupun pada pembacaan gabungan oleh mod:
the answer for <key> is no value the key can hold. Jika nilai Anda sesuai dan kunci tetap tidak berubah, lihat mengapa kunci tidak berlaku.
Tangani peristiwa hook pengaturan
Hook pengaturan adalah hook perintah, HTTP, prompt, dan agent yang Anda konfigurasi dalam file pengaturan. Setiap peristiwa hook pengaturan, sepertiStop, SessionEnd, atau PostToolUse, juga merupakan peristiwa bernama classic. diikuti dengan nama peristiwa hook pengaturan tersebut, seperti classic.Stop. e adalah JSON yang diterima hook pengaturan di stdin, termasuk transcript_path. Di tempat penjaga bawaan dimuat, hook pada peristiwa ini dalam mod yang Anda instal tidak berjalan.
Hook ini menggunakan Stop, yang diaktifkan ketika Claude selesai merespons, untuk mencatat lokasi penyimpanan transkrip sesi:
next(e), sehingga hook hanya mengamati peristiwa dan tidak mengubah apa pun tentang cara giliran berakhir.
Berjalan berdampingan dengan mod lain
Beberapa mod dapat menangani event yang sama, dan salah satu di antaranya bisa gagal. Jika mod Anda memblokir panggilan tool, periksa posisinya dalam rantai dan apa yang terjadi ketika hook-nya gagal.Urutan eksekusi mod
Hook pada event yang sama membentuk satu rantai middleware.next milik setiap mod memanggil hook milik mod berikutnya, dan next terakhir mencapai perilaku Claude Code itu sendiri. Mod pertama adalah yang paling luar: mod ini melihat event sebelum mod lainnya dan melihat hasilnya setelah mod lainnya, serta memutuskan apakah mod lainnya dijalankan sama sekali. Mod yang datang belakangan tidak dapat mencegah mod sebelumnya melihat suatu event.
Claude Code mengurutkan rantai berdasarkan asal setiap mod:
- Penjaga bawaan
sec-default@builtin, sebuah mod yang dibangun ke dalam Claude Code yang ditampilkan oleh/pluginsebagaicc-plugin-sec-default, di tempat mod tersebut dimuat, mod yang dicantumkan organisasi Anda dalamprependPlugins, lalu mod lain mana pun yang dianggap milik organisasi Anda dan tidak ada diappendPlugins - Mod yang Anda instal
- Mod yang dicantumkan organisasi Anda dalam
appendPlugins - Mod lain yang dibangun ke dalam Claude Code
dependencies dalam manifesnya. Di dalam satu modul, hook berjalan sesuai urutan register memanggil on.
Posisi hook pengaturan dalam urutan
HookPreToolUse yang dikonfigurasi dalam file pengaturan juga berjalan selama panggilan tool, pada titik-titik tetap dalam rantai mod:
- Hook
PreToolUsedari pengaturan terkelola: berjalan sebelum hooktool.callmilik mod pertama. Ketika hook terkelola memblokir panggilan tersebut, tidak ada hooktool.callmilik mod mana pun yang berjalan untuk panggilan itu. - Hook
PreToolUsedari setiap file pengaturan lainnya dan darihooks/hooks.jsonmilik plugin: berjalan setelah mod terakhir memanggilnext, sebagai bagian dari perilaku Claude Code itu sendiri. Mod yang menjawabtool.calltanpa memanggilnextmencegah hook tersebut berjalan, dan mod yang memanggilnextmelihat keputusan hook tersebut dalam hasil yang dikembalikannya.
tool.check dipicu setelah hook PreToolUse selesai berjalan. Untuk aturan izin dan keputusan hook PreToolUse yang tidak dapat digantikan oleh allow dari hook tool.check, lihat Memperluas izin dengan hook.
Menangani hook yang gagal
Hook yang gagal tidak merusak sesi, dan Anda dapat menentukan apa yang terjadi sebagai gantinya. Ketika hook tanpa handler.catch melempar error, mengalami timeout, atau mengembalikan hasil dengan bentuk yang salah, apa yang terjadi selanjutnya bergantung pada apakah hook tersebut sudah memanggil next:
- Hook gagal sebelum memanggil
next: Claude Code melewatinya, dan handler berikutnya berjalan menggantikannya - Hook gagal setelah
nextdi-resolve: hasil tersebut tetap berlaku, dan tidak ada yang dijalankan untuk kedua kalinya
my-mod: tool.call hook skipped: threw Error: boom. Tempat Anda membacanya bergantung pada sesi, sebagaimana dicantumkan dalam Mencari tahu mengapa mod tidak melakukan apa-apa. Hook ui.render yang tree-nya tidak lolos validasi dianggap sebagai hook yang mengembalikan bentuk yang salah.
Agar hook yang memblokir panggilan gagal secara tertutup (fail closed), tambahkan handler error .catch yang menjawab menggantikannya. Di sini, guard adalah fungsi hook Anda, dan handler menguji next.called untuk mengetahui apakah guard sudah memanggil next ketika gagal:
guard melempar error atau mengalami timeout pada panggilan Bash, Claude Code memanggil handler dengan event yang sama:
guardgagal sebelum memanggilnext: perintah tidak dijalankan, dan Claude membaca teksdenydengan jenis kegagalan di bagian akhirnyaguardgagal setelah memanggilnext:next(e)milik handler di-resolve ke hasil yang dihasilkan oleh panggilanguardtanpa menjalankan perintah lagi, dan Claude membaca hasil tersebut
guard belum memanggil next, perintah kemudian berlanjut seperti halnya tanpa mod tersebut.
Bentuk handler yang sama cocok untuk penjaga pada prompt.submit atau config.set. Ketika next.called bernilai false, kembalikan penolakan yang dicantumkan dalam referensi event untuk event tersebut: { drop: 'the reason' } untuk prompt.submit, { deny: 'the reason' } untuk config.set.
Pada tool.check dan plugin.register, penolakan yang dikembalikan setelah next di-resolve tetap berlaku, jadi kembalikan penolakan tersebut tanpa menguji next.called:
tool.check: kembalikan{ decision: 'deny', reason: 'the reason' }plugin.register: kembalikan{ refuse: 'the reason' }, seperti yang ditunjukkan dalam Menolak mod ketika pemeriksaan Anda gagal
tool.call, deny yang dikembalikan setelah next di-resolve menahan hasilnya dari Claude.
Langkah berikutnya
- Gunakan mods API: tambahkan perintah dan alat, panggil model, dan jalankan pekerjaan pada timer
- Gambar di antarmuka: tampilkan apa yang dikumpulkan hook Anda dalam panel atau di atas prompt
- Uji mod: naikkan salah satu peristiwa ini dari tes
- Referensi mods: setiap peristiwa, setiap metode mods API, dan batasnya