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

Mulai v2.1.199, tool MCP yang ditandai server-nya dengan _meta["anthropic/requiresUserInteraction"] lebih ketat: hook tidak dapat melewati permintaan persetujuannya dengan "allow", dengan atau tanpa updatedInput, karena Claude Code tidak dapat memastikan bahwa hook telah mengumpulkan interaksi yang dibutuhkan tool tersebut.

Menunda panggilan tool untuk nanti

"defer" ditujukan untuk integrasi yang menjalankan claude -p sebagai subproses dan membaca output JSON-nya, seperti aplikasi Agent SDK atau UI kustom yang dibangun di atas Claude Code. Nilai ini memungkinkan proses pemanggil menjeda Claude pada panggilan tool, mengumpulkan input melalui antarmukanya sendiri, dan melanjutkan dari titik terakhir. Claude Code hanya menghormati nilai ini dalam mode non-interaktif dengan flag -p. Dalam sesi interaktif, Claude Code mencatat peringatan ke log dan mengabaikan hasil hook.

Tool AskUserQuestion adalah kasus yang umum: Claude ingin menanyakan sesuatu kepada pengguna, tetapi tidak ada terminal untuk menjawabnya. Run -p menawarkan AskUserQuestion hanya saat memiliki host izin, seperti tool MCP yang Anda berikan dengan --permission-prompt-tool, jadi mulai run dengan salah satunya. Alur bolak-baliknya bekerja seperti ini:

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

Kolom deferred_tool_use membawa id, name, dan input tool. input adalah parameter yang dihasilkan Claude untuk panggilan 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 ada di disk hingga Anda melanjutkannya, tunduk pada pembersihan retensi cleanupPeriodDays, yang menghapus file sesi setelah 30 hari secara default, mengikuti aturan pembersihan retensi. Jika jawaban belum siap saat Anda melanjutkan, hook dapat mengembalikan "defer" lagi dan proses keluar dengan cara yang sama. Proses pemanggil mengontrol kapan loop dihentikan dengan akhirnya mengembalikan "allow" atau "deny" dari hook.

"defer" hanya berfungsi saat Claude melakukan satu panggilan tool dalam giliran tersebut. Jika Claude melakukan beberapa panggilan tool sekaligus, "defer" diabaikan dengan peringatan dan tool berlanjut melalui alur izin normal. Batasan ini ada karena resume hanya dapat menjalankan ulang satu tool: tidak ada cara untuk menunda satu panggilan dari sekelompok panggilan tanpa membiarkan panggilan lainnya 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 dipicu. Ini terjadi saat server MCP yang menyediakan tool tersebut tidak terhubung untuk sesi yang dilanjutkan. Payload deferred_tool_use tetap disertakan sehingga Anda dapat mengidentifikasi tool mana yang hilang.

PermissionRequest

Berjalan saat Claude Code akan meminta izin Anda untuk menggunakan tool. Dalam sesi yang tidak dapat menampilkan permintaan izin, seperti subagent latar belakang dalam mode non-interaktif, Claude Code tetap menjalankan hook ini, dan jika tidak ada hook yang mengembalikan keputusan, Claude Code menolak panggilan tool tersebut. Gunakan kontrol keputusan PermissionRequest untuk mengizinkan atau menolak atas nama pengguna.

Gunakan event ini saat Anda memerlukan sinyal tepat pada saat Claude meminta izin untuk menggunakan tool. Claude Code menjalankan hook Notification dengan jenis permission_prompt hanya setelah permintaan izin menunggu sekitar enam detik.

Claude Code tidak menjalankan hook PermissionRequest untuk permintaan jaringan dari perintah yang berjalan dalam sandbox. Untuk mendapatkan sinyal untuk permintaan izin tersebut, gunakan jenis notifikasi permission_prompt.

Dicocokkan dengan nama tool, nilai yang sama seperti PreToolUse.

Input PermissionRequest

Hook PermissionRequest menerima kolom tool_name dan tool_input seperti hook PreToolUse, tetapi tanpa tool_use_id. Untuk tool MCP, hook ini juga menerima objek mcp_server. Array permission_suggestions opsional berisi pembaruan izin yang disarankan Claude Code untuk permintaan ini, seperti menambahkan aturan allow atau mengubah mode izin.

Array permission_suggestions bukan daftar persis dari opsi yang Anda lihat, karena setiap dialog izin membangun opsinya sendiri. Beberapa dialog, seperti dialog untuk pengeditan file, sama sekali tidak membaca array tersebut dan menurunkan opsinya dari permintaan itu sendiri. Dialog yang membacanya tetap dapat menahan opsi yang sarannya tetap ada di array, misalnya saat allowManagedPermissionRulesOnly menyembunyikan opsi penyimpanan aturan. Dialog juga dapat menawarkan opsi yang tidak memiliki entri saran, seperti Yes, and switch to auto mode, yang mengubah mode izin secara langsung alih-alih melalui pembaruan izin.

Hook PreToolUse berjalan sebelum setiap panggilan tool, baik memerlukan izin maupun tidak. Hook PermissionRequest hanya berjalan saat Claude Code akan meminta izin Anda, atau saat Claude Code akan menolak secara otomatis panggilan yang tidak dapat menampilkan permintaan izin. Kedua event tersebut tidak dipicu 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"
    }
  ]
}

Kontrol keputusan PermissionRequest

Hook PermissionRequest dapat mengizinkan atau menolak permintaan izin. Selain kolom output JSON yang tersedia untuk semua hook, skrip hook Anda dapat mengembalikan objek decision dengan kolom khusus event berikut:

Hook yang keluar dengan kode 2 tanpa objek decision membiarkan 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"
      }
    }
  }
}

Entri pembaruan izin

Kolom output updatedPermissions dan kolom input permission_suggestions sama-sama menggunakan array objek entri yang sama. Setiap entri memiliki type yang menentukan kolom-kolom lainnya, dan destination yang mengontrol tempat perubahan ditulis.

Field destination pada setiap entri menentukan apakah perubahan tetap berada di memori atau disimpan ke file pengaturan.

Sebuah hook dapat mengembalikan salah satu permission_suggestions yang diterimanya sebagai output updatedPermissions miliknya sendiri.

PostToolUse

Berjalan segera setelah sebuah tool berhasil diselesaikan.

Mencocokkan berdasarkan nama tool, dengan nilai yang sama seperti PreToolUse.

Lakukan pencocokan yang lebih luas ketika nama tool bukan filter yang tepat:

• Untuk menjalankan hook setelah tool apa pun berhasil diselesaikan, hilangkan matcher atau atur ke "*". Hook Anda kemudian dapat mengetahui sendiri apa yang berubah, misalnya dengan menjalankan git status --porcelain, yang juga mencantumkan file yang tidak dilacak yang terlewat oleh git diff. Untuk panggilan 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 mencocokkan Edit|Write ketika perintah Bash atau proses di luar Claude Code menulis ulang file yang sama.

Input PostToolUse

Hook PostToolUse dipicu setelah sebuah tool berhasil dieksekusi. Input mencakup tool_input, yaitu argumen yang dikirim ke tool, dan tool_response, yaitu hasil yang dikembalikannya. Skema persis untuk keduanya bergantung pada tool. Path tool_input pada tool file datang dalam format yang sama seperti untuk PreToolUse: selalu absolut, dengan pemisah native platform, sehingga menggunakan backslash di Windows. Untuk tool MCP, 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
}

Kontrol keputusan PostToolUse

Hook PostToolUse dapat memberikan umpan balik kepada Claude setelah eksekusi tool. Selain field output JSON yang tersedia untuk semua hook, skrip hook Anda dapat mengembalikan field khusus event berikut:

Contoh di bawah ini mengganti output dari panggilan Bash. Nilai pengganti sesuai dengan bentuk output tool Bash:

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

Memberi anotasi pada hasil untuk pengklasifikasi auto mode

Kembalikan classifierContext untuk mengirim catatan singkat tentang hasil panggilan tool ke pengklasifikasi auto mode, bukan ke Claude. Pengklasifikasi tidak pernah menerima hasil tool itu sendiri, sehingga field ini adalah cara yang didukung untuk memberitahunya sesuatu tentang apa yang dikembalikan suatu panggilan sebelum ia meninjau tindakan berikutnya. Field ini memerlukan Claude Code v2.1.236 atau lebih baru.

Contoh di bawah ini memberi tahu pengklasifikasi dari mana output sebuah query berasal:

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

Seberapa besar bobot yang diberikan pengklasifikasi pada catatan tersebut bergantung pada tempat Anda mengonfigurasi hook:

• Hook yang dikonfigurasi di Claude Code: untuk hook dari file pengaturan, plugin, skill, dan frontmatter agent, pengklasifikasi memperlakukan catatan tersebut sebagai konteks yang belum diverifikasi dan disediakan oleh aplikasi. Catatan tersebut tidak pernah menetapkan niat pengguna, dan jika catatan itu mengklaim bahwa Anda menyetujui atau meminta sesuatu, pengklasifikasi memeriksa klaim tersebut terhadap pesan Anda sendiri dalam percakapan
• Callback Agent SDK dalam proses: ketika aplikasi yang menyematkan Claude Code mendaftarkan hook sebagai callback TypeScript SDK dan mengembalikan catatan selama sesi aktif, pengklasifikasi dapat menimbang pernyataan pengguna yang diteruskan dalam catatan sebagai niat pengguna. Pernyataan seperti itu dapat memenuhi persyaratan persetujuan yang akan diterima pengklasifikasi dari pesan yang Anda kirim, tetapi tidak pernah mencabut blokir yang juga tidak dapat dicabut oleh pesan Anda sendiri. Setelah sesi dilanjutkan, Claude Code memperlakukan catatan yang dipulihkan sebagai konteks yang belum diverifikasi. Ketika hook dari kedua kelompok memberi anotasi pada panggilan yang sama, pengklasifikasi memperlakukan catatan gabungan sebagai belum diverifikasi

Claude Code menerapkan batasan berikut saat mengirimkan catatan:

• Panjang: Claude Code membatasi catatan untuk satu panggilan tool hingga 2.000 karakter dan memotong sisanya. Batas ini dibagi di antara setiap hook yang merespons panggilan tersebut
• Hanya respons sinkron: Claude Code mengabaikan field ini dalam respons hook yang berjalan di latar belakang, karena respons tersebut tiba setelah Claude Code mencatat hasil tool
• Panggilan yang tidak dicatat oleh pengklasifikasi: transkrip pengklasifikasi menghilangkan pencarian read-only seperti pembacaan file dan pencarian. Claude Code membuang catatan yang dilampirkan ke salah satu panggilan tersebut
• Interaksi dengan penulisan ulang: ketika catatan menjelaskan output yang Anda ganti dengan updatedToolOutput, kembalikan kedua field dalam respons hook yang sama. Claude Code membuang catatan tersebut jika penulisan ulang itu ditolak atau penulisan ulang hook lain menggantikannya. Claude Code mengirimkan catatan yang Anda kembalikan tanpa penulisan ulang bahkan ketika hook lain menulis ulang output

PostToolUseFailure

Berjalan ketika sebuah tool yang sudah mulai dieksekusi gagal: tool melempar error, atau tool MCP mengembalikan hasil error. Gunakan ini untuk mencatat kegagalan, mengirim peringatan, atau memberikan umpan balik korektif kepada Claude.

Mencocokkan berdasarkan nama tool, dengan nilai yang sama seperti PreToolUse.

Input PostToolUseFailure

Hook PostToolUseFailure menerima field tool_name dan tool_input yang sama seperti PostToolUse, bersama dengan informasi error sebagai field tingkat atas. Untuk tool MCP, hook juga menerima objek mcp_server. Misalnya, perintah npm test yang gagal mungkin mengirimkan:

{
  "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 merupakan teks yang sama yang diterima Claude sebagai hasil tool yang gagal. Formatnya bervariasi menurut tool dan jenis kegagalan. Dasarkan 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 berjalan dan keluar menghasilkan baris pertama Exit code N, lalu output apa pun yang dihasilkan perintah sebagai satu blok dengan stdout dan stderr yang saling berselang-seling
• Sebuah payload juga dapat membawa pesan kegagalan polos tanpa baris exit code, ketika Claude Code tidak dapat memulai proses shell itu sendiri
• Claude Code memotong bagian tengah string panjang di sekitar penanda ... [N characters truncated] ..., dan dapat menyisipkan baris miliknya sendiri, seperti Command timed out after 2m 0s

Kontrol keputusan PostToolUseFailure

Hook PostToolUseFailure dapat memberikan konteks kepada Claude setelah kegagalan tool. Selain field output JSON yang tersedia untuk semua hook, skrip hook Anda dapat mengembalikan field khusus event berikut:

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

PostToolBatch

Berjalan sekali setelah setiap panggilan tool dalam satu batch selesai diproses, sebelum Claude Code mengirim permintaan berikutnya ke model. PostToolUse dipicu sekali per tool, yang berarti ia dipicu secara bersamaan ketika Claude melakukan panggilan tool paralel. PostToolBatch dipicu tepat sekali dengan batch lengkap, sehingga merupakan tempat yang tepat untuk menyuntikkan konteks yang bergantung pada kumpulan tool yang berjalan, bukan pada satu tool tertentu. Tidak ada matcher untuk event ini.

Input PostToolBatch

Selain field input umum, hook PostToolBatch menerima tool_calls, sebuah array yang menjelaskan setiap panggilan 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\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

tool_response berisi konten yang sama yang diterima model dalam blok tool_result yang sesuai. Nilainya adalah string terserialisasi atau array content-block, persis seperti yang dikeluarkan tool. Untuk Read, itu berarti teks dengan awalan nomor baris, bukan konten file mentah. Respons bisa berukuran besar, jadi parse hanya field yang Anda butuhkan.

Kontrol keputusan PostToolBatch

Hook PostToolBatch dapat menyuntikkan konteks untuk Claude. Selain field output JSON yang tersedia untuk semua hook, skrip hook Anda dapat mengembalikan field khusus event berikut:

{
  "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 agentic loop sebelum panggilan model berikutnya. Pesan pemblokiran berasal dari reason atau stopReason JSON, atau dari stderr pada exit 2. Anda melihatnya sebagai peringatan di transkrip, dan pesan itu tetap ada dalam percakapan, sehingga Claude melihatnya ketika percakapan berlanjut.

PermissionDenied

Berjalan ketika auto mode menolak panggilan tool, termasuk ketika ia menolak tanpa putusan pengklasifikasi karena pemeriksaan keamanan yang terpisah dari auto mode menolak permintaan pengklasifikasi itu sendiri atau responsnya tidak dapat di-parse. Hook ini hanya dipicu dalam auto mode: hook ini tidak berjalan ketika Anda menolak dialog izin secara manual, ketika hook PreToolUse memblokir panggilan, atau ketika aturan deny cocok. Gunakan ini untuk mencatat penolakan, menyesuaikan konfigurasi, atau memberi tahu model bahwa ia boleh mencoba ulang panggilan tool.

Mencocokkan berdasarkan nama tool, dengan nilai yang sama seperti PreToolUse.

Input PermissionDenied

Selain field input umum, hook PermissionDenied menerima tool_name, tool_input, tool_use_id, dan reason. Untuk tool MCP, hook 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]"
}

Kontrol keputusan PermissionDenied

Hook PermissionDenied dapat memberi tahu model bahwa ia boleh mencoba ulang panggilan tool yang ditolak. Kembalikan objek JSON dengan hookSpecificOutput.retry diatur ke true:

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

Ketika retry bernilai true, Claude Code menambahkan pesan ke percakapan yang memberi tahu model bahwa ia boleh mencoba ulang panggilan tool. Claude Code tidak membatalkan penolakan itu sendiri. Jika hook Anda tidak mengembalikan JSON, atau mengembalikan retry: false, penolakan tetap berlaku dan model menerima pesan penolakan asli.

Claude Code mengabaikan retry: true ketika pengklasifikasi tidak menghasilkan putusan atas tindakan tersebut: responsnya tidak dapat di-parse, atau pemeriksaan keamanan yang terpisah dari auto mode menolak permintaan pengklasifikasi itu sendiri. Untuk penolakan tersebut, Claude Code sudah memberi tahu model dalam pesan penolakan apakah harus mencoba ulang nanti atau melanjutkan.

Notification

Berjalan ketika Claude Code mengirim notifikasi. Mencocokkan berdasarkan jenis notifikasi. Hilangkan matcher untuk menjalankan hook untuk semua jenis notifikasi.

Anda menerima event hook ini bahkan ketika notifikasi desktop dimatikan: pengaturan preferredNotifChannel, termasuk notifications_disabled, hanya mengubah cara Anda diberi peringatan, bukan apakah hook Anda berjalan.

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

Jenis 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 permintaan jaringan dari perintah yang di-sandbox memerlukan Claude Code v2.1.246 atau lebih baru.

agent_needs_input untuk pertanyaan penyiapan terminal dari rekan tim memerlukan Claude Code v2.1.248 atau lebih baru.

Claude Code mengatur waktu permission_prompt secara berbeda dalam sesi di mana ia mengirim permintaan izin ke callback canUseTool milik Agent SDK, yang merupakan cara Claude Desktop dan ekstensi VS Code menghosting Claude Code:

• permission_prompt akan muncul sekitar enam detik setelah Claude meminta izin. Claude Code tidak menundanya saat 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 dipicu dalam sesi ini.

Gunakan matcher terpisah untuk menjalankan handler yang berbeda bergantung pada jenis notifikasi. Konfigurasi ini memicu skrip peringatan khusus izin ketika Claude memerlukan persetujuan izin dan notifikasi yang berbeda ketika Claude dalam keadaan 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"
          }
        ]
      }
    ]
  }
}

Input Notification

Selain field input umum, hook Notification menerima message dengan teks notifikasi, title opsional, dan notification_type yang menunjukkan jenis mana yang dipicu.

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

Hook Notification tidak dapat memblokir atau memodifikasi notifikasi. Claude Code membuang field systemMessage dan continue miliknya tetapi tetap mengeluarkan terminalSequence, yang menjadi andalan contoh notifikasi desktop. Hook Notification ditujukan untuk efek samping seperti meneruskan notifikasi ke layanan eksternal.

SubagentStart

Berjalan ketika Claude memunculkan subagent dengan tool Agent, ketika Claude melanjutkan subagent, dan setiap kali rekan tim tim agent dalam proses menangani pesan baru. Mendukung matcher untuk memfilter berdasarkan nama jenis agent. Untuk agent bawaan, ini adalah nama agent seperti general-purpose, Explore, atau Plan. Untuk subagent kustom, ini adalah field name dari frontmatter agent, bukan nama file.

Untuk subagent yang disertakan oleh plugin, jenis agent adalah pengidentifikasi dengan cakupan plugin seperti my-plugin:reviewer, bukan nama frontmatter polos. Titik dua menempatkan nama dengan cakupan plugin pada jalur regular expression, jadi jangkarkan matcher dengan ^ dan $ untuk kecocokan persis: ^my-plugin:reviewer$.

Input SubagentStart

Selain field input umum, hook SubagentStart menerima agent_id dengan pengidentifikasi unik untuk subagent dan agent_type dengan nama agent yang difilter oleh matcher.

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

Hook SubagentStart tidak dapat memblokir pembuatan subagent, tetapi dapat menyuntikkan konteks ke dalam subagent. Selain field output JSON yang tersedia untuk semua hook, Anda dapat mengembalikan:

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

Ketika hook berjalan lagi untuk subagent yang sama, Claude Code menyuntikkan konteks yang dikembalikan hanya jika konteks subagent belum menyimpan salinan dari eksekusi sebelumnya. Salinan yang disuntikkan saat peluncuran tetap di tempatnya, sehingga prompt cache subagent tetap utuh. Setelah auto-compaction membuang salinan tersebut, Claude Code menyuntikkan konteks dari eksekusi berikutnya lagi.

SubagentStop

Berjalan ketika subagent Claude Code telah selesai merespons. Mencocokkan berdasarkan jenis agent, dengan nilai yang sama seperti SubagentStart.

Input SubagentStop

Selain field input umum, hook SubagentStop menerima stop_hook_active, agent_id, agent_type, agent_transcript_path, dan last_assistant_message. Field agent_type adalah nilai yang digunakan untuk pemfilteran matcher. transcript_path adalah transkrip sesi utama, sedangkan agent_transcript_path adalah transkrip milik subagent sendiri yang disimpan dalam folder subagents/ bersarang. Field last_assistant_message berisi konten teks dari respons akhir subagent, sehingga hook dapat mengaksesnya tanpa mem-parse file transkrip.

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

matcher yang menyebutkan jenis agent tidak cocok dengan agent_type yang kosong. Hook yang matcher-nya dihilangkan, "", atau "*", atau berupa regular expression yang cocok dengan string kosong, juga berjalan untuk event dengan agent_type kosong.

Pada Claude Code v2.1.271 atau lebih baru, subagent yang berjalan dengan tool SubagentHandback mengirimkan laporannya melalui tool tersebut sebelum berhenti. Field last_assistant_message kemudian berisi teks penutup subagent, jika ada, yang bukan laporan yang dikirimkan. Laporan tersebut adalah input message dari panggilan itu, yang diterima oleh hook PreToolUse atau PostToolUse yang mencocokkan SubagentHandback sebagai tool_input.message.

Hook SubagentStop juga menerima array background_tasks dan session_crons yang dijelaskan di bawah Input Stop. Kedua array tersebut dicakup 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": []
}

Hook SubagentStop menggunakan format kontrol keputusan yang sama seperti hook Stop, 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. Hook yang memblokir dengan keluar menggunakan kode 2 mengirimkan pesan stderr-nya dengan cara yang sama. Untuk menyuntikkan konteks ke sesi induk setelah subagent kembali, gunakan hook PostToolUse pada tool Agent sebagai gantinya.

TaskCreated

Berjalan ketika sebuah tugas sedang dibuat melalui tool TaskCreate. Gunakan ini untuk menegakkan konvensi penamaan, mewajibkan deskripsi tugas, atau mencegah tugas tertentu dibuat. Dalam sesi tanpa tool Task, event ini tidak dipicu.

Hook TaskCreated tidak mendukung matcher dan dipicu pada setiap kejadian.

Input TaskCreated

Selain field input umum, hook TaskCreated 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"
}

Kontrol keputusan TaskCreated

Hook TaskCreated dapat memblokir pembuatan dengan dua cara. Dengan cara mana pun, Claude Code menghapus tugas dan mengembalikan pesan Anda kepada Claude sebagai error tool. Claude Code mengabaikan continue: false dari event ini dan Claude tetap bekerja.

• Exit code 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 diwajibkan:

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

Berjalan ketika sebuah tugas sedang ditandai sebagai selesai. Ini dipicu dalam dua situasi: ketika agent mana pun secara eksplisit menandai tugas sebagai selesai melalui tool TaskUpdate, atau ketika rekan tim tim agent menyelesaikan gilirannya dengan tugas yang sedang berlangsung. Gunakan ini untuk menegakkan kriteria penyelesaian seperti lolos pengujian atau pemeriksaan lint sebelum tugas dapat ditutup.

Hook TaskCompleted tidak mendukung matcher dan dipicu pada setiap kejadian.

Input TaskCompleted

Selain field input umum, hook TaskCompleted 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"
}

Kontrol keputusan TaskCompleted

Hook TaskCompleted mendukung dua cara untuk mengontrol penyelesaian tugas:

• Exit code 2: tugas tidak ditandai sebagai selesai dan pesan stderr diumpankan kembali ke model sebagai umpan balik.
• JSON {"continue": false, "stopReason": "..."}: ketika rekan tim yang menyelesaikan gilirannya memicu event, rekan tim dihentikan sepenuhnya, sesuai dengan perilaku hook Stop. stopReason ditampilkan kepada pengguna. Ketika tool TaskUpdate memicu event, Claude Code mengabaikan continue: false; exit code 2 tetap memblokir penyelesaian.

Contoh ini menjalankan pengujian dan memblokir penyelesaian tugas jika pengujian gagal:

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

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

exit 0

Stop

Berjalan ketika agent utama Claude Code telah selesai merespons. Tidak berjalan jika penghentian terjadi karena interupsi pengguna. Error API memicu StopFailure sebagai gantinya.

Input Stop

Selain field input umum, hook Stop menerima stop_hook_active, last_assistant_message, background_tasks, dan session_crons. Field stop_hook_active bernilai true ketika Claude Code sudah melanjutkan sebagai akibat dari hook stop. Periksa nilai ini atau proses transkrip untuk menghindari pemblokiran pada kondisi yang tidak akan pernah terselesaikan. Claude Code menerapkan batas 8 kelanjutan berturut-turut: setelah hook stop melanjutkan giliran delapan kali berturut-turut, Claude Code menimpa blokir berikutnya dan mengakhiri giliran. Untuk menaikkan batas, atur CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Field last_assistant_message berisi konten teks dari respons akhir Claude, sehingga hook dapat mengaksesnya tanpa mem-parse file transkrip. Untuk hook yang bertindak pada giliran yang baru saja selesai, seperti hook pembacaan dengan suara keras atau notifikasi, gunakan field ini alih-alih membaca transcript_path: file transkrip tidak dijamin menyertakan pesan akhir pada saat Stop di semua versi.

Array background_tasks dan session_crons memungkinkan hook membedakan "sesi sudah 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 berjalan atau dijadwalkan.

Setiap entri dalam background_tasks menjelaskan satu tugas yang sedang berjalan dan menggunakan field berikut:

Setiap entri dalam session_crons menjelaskan satu wakeup terjadwal dengan cakupan sesi, yang bersumber dari CronCreate, ScheduleWakeup, dan /loop:

Contoh ini menunjukkan input Stop dengan satu tugas shell yang sedang berjalan 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"
    }
  ]
}

Kontrol keputusan Stop

Hook Stop dan SubagentStop dapat mengontrol apakah Claude melanjutkan. Selain field output JSON yang tersedia untuk semua hook, skrip hook Anda dapat mengembalikan field khusus event berikut:

Hook yang memblokir dengan keluar menggunakan kode 2 dirutekan dengan cara yang sama seperti reason: Claude menerima pesan stderr sebagai penjelasan mengapa ia harus melanjutkan.

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

Gunakan additionalContext ketika hook berfungsi sesuai rancangan dan memberikan panduan kepada Claude, seperti "jalankan test suite sebelum selesai". Ini menjaga percakapan tetap berjalan melalui perlindungan loop yang sama seperti decision: "block", yaitu input stop_hook_active dan batas 8 kelanjutan berturut-turut, tetapi transkrip melabelinya Stop hook feedback dan tidak ada notifikasi error hook yang ditampilkan:

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

StopFailure

Berjalan sebagai pengganti Stop ketika giliran berakhir karena error API. Claude Code mengabaikan output dan exit code hook, kecuali terminalSequence. Gunakan ini untuk mencatat kegagalan, mengirim peringatan, atau mengambil tindakan pemulihan ketika Claude tidak dapat menyelesaikan respons karena rate limit, masalah autentikasi, atau error API lainnya.

Input StopFailure

Selain field input umum, hook StopFailure menerima error, error_details opsional, dan last_assistant_message opsional. Field error mengidentifikasi jenis error 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"
}

Hook StopFailure tidak memiliki kontrol keputusan. Hook ini hanya berjalan untuk tujuan notifikasi dan pencatatan log.

TeammateIdle

Berjalan ketika rekan tim tim agent akan menjadi idle setelah menyelesaikan gilirannya. Gunakan ini untuk menegakkan gerbang kualitas sebelum rekan tim berhenti bekerja, seperti mewajibkan lolos pemeriksaan lint atau memverifikasi bahwa file output ada.

Hook TeammateIdle tidak mendukung matcher dan dipicu pada setiap kejadian.

Input TeammateIdle

Selain field input umum, hook TeammateIdle 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"
}

Kontrol keputusan TeammateIdle

Hook TeammateIdle mendukung dua cara untuk mengontrol perilaku rekan tim:

• Exit code 2: rekan tim menerima pesan stderr sebagai umpan balik dan terus bekerja alih-alih menjadi idle.
• JSON {"continue": false, "stopReason": "..."}: menghentikan rekan tim sepenuhnya, sesuai dengan perilaku hook Stop. stopReason ditampilkan kepada pengguna.

Contoh ini memeriksa bahwa artefak build ada sebelum mengizinkan rekan tim 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

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

Claude Code menjalankan hook ConfigChange ketika file pengaturan, file kebijakan terkelola, atau file skill berubah. Untuk kebijakan terkelola, Claude Code menjalankannya hanya ketika managed-settings.json atau file di managed-settings.d/ berubah. Claude Code menerapkan pengaturan yang dikelola server dan perubahan pada preferensi terkelola macOS atau kebijakan registri Windows tanpa menjalankannya. Di WSL dengan wslInheritsWindowsSettings, Claude Code juga menerapkan file pengaturan terkelola sisi Windows yang berubah pada polling kebijakannya tanpa menjalankannya.

Matcher memfilter berdasarkan 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": []
          }
        ]
      }
    ]
  }
}

Input ConfigChange

Selain field input umum, hook ConfigChange menerima source dan secara opsional file_path. Field source menunjukkan jenis 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"
}

Kontrol keputusan ConfigChange

Hook ConfigChange dapat memblokir perubahan konfigurasi agar tidak berlaku. Gunakan exit code 2 atau decision JSON untuk mencegah perubahan. Ketika diblokir, pengaturan baru tidak diterapkan ke sesi yang sedang berjalan.

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

Perubahan policy_settings tidak dapat diblokir. Hook tetap dipicu untuk sumber policy_settings ketika file pengaturan terkelola di mesin berubah, sehingga Anda dapat menggunakannya untuk mencatat pengeditan tersebut, tetapi keputusan pemblokiran apa pun akan diabaikan. Ini memastikan pengaturan yang dikelola perusahaan selalu berlaku. Claude Code tidak menjalankan hook ConfigChange ketika pengaturan yang dikelola server tiba atau diperbarui.

Claude Code menindaklanjuti keputusan pemblokiran dari output JSON hook ConfigChange dan membuang systemMessage dan continue. Perubahan yang diblokir tidak memunculkan pesan apa pun kepada Anda atau kepada Claude, baik Anda memblokir dengan reason maupun dengan stderr pada exit 2. Claude Code hanya menulis satu baris ke log debug.

CwdChanged

Berjalan ketika perintah shell dalam percakapan utama mengubah direktori kerja, misalnya ketika Claude mengeksekusi perintah cd. Gunakan ini untuk bereaksi terhadap perubahan direktori: memuat ulang environment variable, mengaktifkan toolchain khusus proyek, atau menjalankan skrip penyiapan secara otomatis. Berpasangan dengan FileChanged untuk tool seperti direnv yang mengelola environment per direktori.

Hook CwdChanged memiliki akses ke CLAUDE_ENV_FILE. Variabel yang ditulis ke file tersebut bertahan ke perintah Bash berikutnya hingga event CwdChanged berikutnya, ketika Claude Code menghapusnya.

CwdChanged tidak mendukung matcher dan dipicu pada setiap kejadian.

Input CwdChanged

Selain field input umum, hook CwdChanged 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"
}

Output CwdChanged

Selain field output JSON yang tersedia untuk semua hook, hook CwdChanged dapat mengembalikan watchPaths untuk secara dinamis mengatur path file mana yang dipantau oleh FileChanged:

Hook CwdChanged tidak memiliki kontrol keputusan. Hook ini tidak dapat memblokir perubahan direktori.

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

DirectoryAdded

Berjalan setelah Anda menambahkan direktori kerja di tengah sesi dengan perintah /add-dir, atau setelah klien SDK menambahkannya dengan permintaan kontrol register_repo_root. Gunakan ini untuk menyiapkan repositori yang baru ditambahkan, misalnya dengan menginstal dependensinya.

Claude Code tidak memicu event ini ketika:

• Anda meneruskan direktori dengan flag startup --add-dir; SessionStart mencakup direktori tersebut
• Anda menambahkan direktori pada tab Workspace di /permissions
• Anda menambahkan direktori yang sudah merupakan direktori kerja atau berada di dalamnya

Claude Code memicu DirectoryAdded setelah menyegarkan status sandbox dan izin, sehingga tool yang di-sandbox sudah melihat direktori baru ketika hook Anda berjalan. Perintah hook itu sendiri berjalan tanpa sandbox.

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

Matcher memfilter berdasarkan cara direktori ditambahkan:

Input DirectoryAdded

Selain field input umum, hook DirectoryAdded 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"
}

Hook DirectoryAdded tidak memiliki kontrol keputusan. Hook ini tidak dapat memblokir penambahan, yang sudah selesai saat hook berjalan. Claude Code membuang field continue dari output JSON-nya dan memunculkan sisanya secara berbeda per sumber:

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

FileChanged

Berjalan ketika file yang dipantau berubah di disk. Claude Code mendeteksi perubahan dengan pemantau filesystem, bukan dengan memeriksa panggilan tool, sehingga ia menjalankan hook apa pun yang mengubah file tersebut: panggilan tool Edit atau Write, skrip yang dijalankan Claude dengan Bash, atau proses yang sepenuhnya berada di luar Claude Code. Penggunaan umum adalah memuat ulang environment variable ketika file konfigurasi proyek berubah.

matcher untuk event ini memiliki dua peran:

• Membangun daftar pantauan: nilainya dipisah berdasarkan | dan setiap segmen didaftarkan sebagai nama file literal di direktori kerja, sehingga ".envrc|.env" memantau tepat kedua file tersebut. Pola regex tidak berguna di sini: nilai seperti ^\.env akan memantau file yang secara literal bernama ^\.env.
• Memfilter hook mana yang berjalan: ketika file yang dipantau berubah, nilai yang sama memfilter grup hook mana yang berjalan menggunakan aturan matcher standar terhadap basename file yang berubah.

Contoh ini menormalkan akhir baris di data.csv setelah perubahan apa pun, termasuk perintah 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 absolut file yang berubah dari field file_path pada input JSON di stdin. Penjaga grep-nya menguji hal yang sama yang dihapus oleh perl, yaitu CR di akhir baris, sehingga eksekusi setelah normalisasi keluar tanpa menyentuh file. Penjaga yang lebih longgar akan berulang tanpa henti, karena perl -i menulis ulang file bahkan ketika tidak mengganti apa pun dan Claude Code menjalankan hook lagi setelah setiap penulisan ulang. Simpan skrip ini di /path/to/normalize-line-endings.sh dan jadikan dapat dieksekusi:

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

Untuk memastikan hook berfungsi, minta Claude menambahkan baris CRLF ke data.csv dengan perintah Bash. Claude Code menjalankan hook dan file akhirnya memiliki akhir baris LF.

Untuk memantau file yang tidak dapat Anda sebutkan di awal, kembalikan watchPaths dari hook untuk memperbarui daftar pantauan secara dinamis. Claude Code memulai pemantau hanya ketika sesuatu menyebutkan file untuk dipantau, jadi isi awal daftar dengan grup FileChanged yang matcher-nya menyebutkan setidaknya satu file, atau dengan hook SessionStart atau CwdChanged yang mengembalikan watchPaths. Matcher tetap memfilter grup hook mana yang berjalan 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 pantauan. Matcher "*" juga cocok dengan setiap file, tetapi Claude Code mendaftarkannya dalam daftar pantauan seperti nilai lainnya, sebagai file literal bernama *.

Hook FileChanged memiliki akses ke CLAUDE_ENV_FILE. Variabel yang ditulis ke file tersebut bertahan ke perintah Bash berikutnya hingga event CwdChanged berikutnya, ketika Claude Code menghapusnya.

Input FileChanged

Selain field input umum, hook FileChanged 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"
}

Output FileChanged

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

Hook FileChanged tidak memiliki kontrol keputusan. Hook ini tidak dapat memblokir terjadinya perubahan file.

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

WorktreeCreate

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

Karena hook sepenuhnya menggantikan perilaku default, .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 Output WorktreeCreate untuk cara setiap jenis hook mengembalikan path.

Claude Code menindaklanjuti keberhasilan hook dan path yang dikembalikan, serta membuang systemMessage dan continue.

Contoh ini membuat salinan kerja SVN dan mencetak path untuk digunakan Claude Code. 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 baru ke direktori baru, dan mencetak path direktori. echo pada baris terakhir adalah apa yang dibaca Claude Code sebagai path worktree. Alihkan output lainnya ke stderr agar tidak mengganggu path.

Input WorktreeCreate

Selain field input umum, hook WorktreeCreate menerima field name. Ini adalah pengidentifikasi slug untuk worktree baru, baik yang ditentukan oleh pengguna maupun yang dibuat secara otomatis, 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"
}

Output WorktreeCreate

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

• Hook command (type: "command"): cetak path sebagai baris tidak kosong terakhir dari stdout. Claude Code menghapus kode escape ANSI sebelum membaca baris tersebut, sehingga banner startup shell yang dicetak sebelum echo Anda diabaikan. Alihkan output hook lainnya ke stderr.
• Hook HTTP (type: "http"): kembalikan { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } di body respons.

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

Claude Code menyelesaikan path relatif terhadap direktori tempat hook dijalankan, sambil menyederhanakan segmen . atau .. di dalamnya. Jika path yang dihasilkan bukan direktori yang dapat dimasuki Claude Code, sesi mencetak error yang menyebutkan path tersebut dan keluar dengan kode 1.

Claude Code menolak path absolut yang berisi segmen . atau .., serta path apa pun yang melewati symlink di bawah root repositori, karena symlink yang di-commit ke repositori dapat mengalihkan worktree ke luar repositori. Error tersebut menyebutkan komponen yang ditolak. Kembalikan path yang dinormalisasi yang tidak melewati symlink di dalam repositori. Sebelum v2.1.216, pembuatan worktree mengikuti path dari hook tanpa penyaringan ini.

WorktreeRemove

Berjalan saat worktree sedang dihapus. Ini adalah pasangan pembersihan dari WorktreeCreate. Event ini dipicu saat:

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

Untuk worktree berbasis git, Claude Code menangani pembersihan secara otomatis dengan git worktree remove. Jika Anda mengonfigurasi hook WorktreeCreate, pasangkan dengan hook WorktreeRemove untuk mengontrol pembersihan worktree yang dibuatnya:

• Tanpa hook WorktreeRemove: saat Anda keluar dari sesi --worktree dan memilih penghapusan, Claude Code melakukan fallback ke git worktree remove --force pada path yang dikembalikan hook WorktreeCreate Anda, sehingga worktree yang dikenali git akan dihapus. Worktree yang tidak dikenali git, misalnya yang dibuat hook Anda dengan sistem kontrol versi non-git, tetap ada di disk. Untuk apa yang dilakukan penghapusan sesi latar belakang terhadap worktree yang dibuat hook, lihat aturan penghapusan di agent view.
• Hook keluar dengan 0: worktree dianggap telah dihapus. Claude Code tidak membaca apa pun lagi dari hook, jadi pastikan hook Anda telah menghapus direktori tersebut.
• Hook keluar dengan non-zero: penghapusan gagal jika direktori di worktree_path masih ada setelahnya, dan worktree tetap ada di disk tanpa fallback git. Hook yang menghapus direktori sebelum keluar dengan non-zero dianggap telah dihapus. Untuk cara kegagalan dilaporkan, lihat Input WorktreeRemove.

Claude Code tidak pernah menghapus branch milik worktree yang dibuat hook, karena Claude Code hanya mengetahui path yang dikembalikan hook WorktreeCreate Anda. Jika hook WorktreeCreate Anda membuat branch, hapus branch tersebut di hook WorktreeRemove Anda.

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

Untuk penghapusan sesi latar belakang, Claude Code memverifikasi path worktree yang tersimpan sebelum menjalankan hook dan menolak path yang merupakan symlink atau melewati symlink di bawah root repositori. Hook berjalan untuk worktree yang masih berisi file hanya ketika Anda mengonfirmasi penghapusan di agent view; untuk worktree seperti itu, claude rm justru mempertahankan sesi dan worktree. Sebelum v2.1.216, hook berjalan pada path yang tersimpan tanpa pemeriksaan ini.

Claude Code meneruskan path yang dikembalikan oleh WorktreeCreate sebagai worktree_path di input hook. Contoh ini membaca path tersebut dan menghapus direktorinya:

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

Input WorktreeRemove

Selain field input umum, hook WorktreeRemove menerima field worktree_path, yaitu 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"
}

Exit code hook WorktreeRemove menentukan hasilnya. Ketika hook keluar dengan non-zero dan direktori di worktree_path masih ada setelahnya, penghapusan gagal:

• Worktree tetap ada di disk, dan perintah serta stderr hook masuk ke log debug.
• Jika Anda sedang menghapus sesi latar belakang, sesi tersebut juga tetap ada. Pesan penolakan di agent view melaporkan bagaimana hook berakhir, seperti exited 1, mengutip bagian awal stderr-nya, dan menyebutkan apakah menghapus sesi lagi akan tetap menghapus direktori tersebut.

PreCompact

Berjalan 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 /compact manual, pesan stderr ditampilkan kepada pengguna. Anda juga dapat memblokir dengan mengembalikan JSON dengan "decision": "block".

Memblokir compaction otomatis memiliki efek berbeda tergantung kapan dipicu. Jika compaction dipicu secara proaktif sebelum batas konteks, Claude Code melewatinya dan percakapan berlanjut tanpa dipadatkan. Jika compaction dipicu untuk memulihkan dari error batas konteks yang sudah dikembalikan oleh API, error yang mendasarinya muncul dan permintaan saat ini gagal.

Claude Code membuang field systemMessage dan continue dari hook PreCompact.

Input PreCompact

Selain field input umum, hook PreCompact menerima trigger dan custom_instructions. Untuk manual, custom_instructions berisi apa yang diteruskan pengguna ke /compact dan bernilai null jika pengguna tidak meneruskan apa pun. Untuk auto, custom_instructions bernilai 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

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

Nilai matcher yang sama berlaku seperti untuk PreCompact:

Input PostCompact

Selain field input umum, hook PostCompact menerima trigger dan compact_summary. Field 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..."
}

Hook PostCompact tidak memiliki kontrol keputusan. Hook ini tidak dapat memengaruhi hasil compaction tetapi dapat melakukan tugas lanjutan.

PreModelSwitch

Berjalan sebelum Claude Code menerapkan peralihan model yang diminta oleh Anda atau klien. Gunakan untuk memblokir peralihan, meminta konfirmasi, atau menampilkan biaya peralihan sebelum terjadi.

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

• /model <name> dan pemilih /model
• Pemilih model Option+P atau Alt+P
• Pengaturan Model di /config
• Mengaktifkan fast mode ketika hal 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 hook PreModelSwitch untuk peralihan yang dilakukannya sendiri, seperti fallback model otomatis atau memulihkan model saat Anda melanjutkan sesi. Perubahan tersebut hanya mencapai PostModelSwitch.

Claude Code membandingkan matcher dengan nama kanonis model tujuan peralihan sesi, dengan mengabaikan sufiks [1m]. Alias seperti opus, ID model bertanggal, dan ID khusus penyedia seperti ID model Amazon Bedrock semuanya cocok dengan satu nama kanonis yang menjadi hasil resolusinya, sehingga claude-opus-5 mencakup setiap penulisan Opus 5.

Ketika Claude Code tidak dapat menentukan nama kanonis untuk target, misalnya ID model kustom yang hanya dikenal oleh LLM gateway Anda, Claude Code menjalankan setiap hook PreModelSwitch terlepas dari matcher. Oleh karena itu, hook yang memblokir sebaiknya memeriksa to_model dari inputnya alih-alih hanya mengandalkan matcher.

Tulis matcher sebagai nama persis, daftar yang dipisahkan | seperti claude-opus-4-6|claude-opus-5, atau regular expression seperti .*opus.*. Contoh ini menggunakan matcher nama persis dan juga memeriksa to_model dari input hook, sehingga menolak peralihan ke Opus 4.6 dengan keluar menggunakan kode 2 dan membiarkan target lain lolos:

{
"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 memastikan hook berfungsi, jalankan /model claude-opus-4-6 dari sesi yang menjalankan model lain. Claude Code mempertahankan model saat ini dan melaporkan bahwa hook PreModelSwitch memblokir peralihan, dengan pesan Anda sebagai alasannya.

Input PreModelSwitch

Selain field input umum, hook PreModelSwitch menerima field dalam tabel ini. Lima field terakhir menjelaskan biaya pengiriman ulang percakapan ke model baru, sehingga hook dapat menampilkan angka tersebut sebelum peralihan 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"
}

Kontrol keputusan PreModelSwitch

Hook PreModelSwitch dapat membatalkan peralihan, meminta pengguna untuk mengonfirmasinya, atau membiarkannya berlanjut. Exit code 2 atau decision: "block" tingkat atas membatalkan peralihan.

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

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

Contoh ini meminta pengguna untuk mengonfirmasi 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 hook PreModelSwitch mengembalikan keputusan yang berbeda, urutan prioritasnya adalah deny > ask > allow.

Claude Code menampilkan kepada pengguna setiap systemMessage yang dikembalikan hook Anda terlepas dari keputusannya, sehingga hook pelaporan biaya dapat mengembalikan {"systemMessage": "..."} dan keluar dengan 0.

Hook PreModelSwitch yang tidak merespons sebelum timeout-nya akan memblokir peralihan. Sebaliknya, pada PreToolUse, hook command yang mengalami timeout membiarkan panggilan tool berlanjut. Timeout default untuk event ini adalah 30 detik. PreModelSwitch hanya menjalankan hook command, http, dan mcp_tool, sehingga 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 peralihan, seperti dijelaskan di Exit code lainnya.

PostModelSwitch

Berjalan setelah model sesi berubah. Gunakan untuk memberi Claude panduan khusus model tanpa mengedit setiap CLAUDE.md, misalnya instruksi tingkat organisasi yang berlaku pada model tertentu.

PostModelSwitch memerlukan Claude Code v2.1.251 atau lebih baru. Hook ini tidak dapat memblokir, karena model sudah berubah. Claude Code menjalankan hook PostModelSwitch setelah salah satu perubahan berikut:

• Peralihan yang diminta oleh Anda atau klien
• Fallback model otomatis, yang mengubah model sesi
• Pengaturan seperti opusplan yang masuk atau keluar dari plan mode
• Claude Code memulihkan model saat Anda melanjutkan sesi

Claude Code tidak menjalankan hook PostModelSwitch ketika model dari rantai model fallback melayani sebuah giliran, karena substitusi tersebut hanya berlangsung satu giliran dan tidak mengubah model sesi.

Matcher mengikuti aturan yang sama seperti PreModelSwitch: Claude Code membandingkannya dengan nama kanonis model tujuan peralihan sesi.

Contoh ini menambahkan panduan setiap kali model sesi berubah ke model Opus mana 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 memastikan hook berfungsi, beralihlah ke model Opus dari sesi yang menjalankan model lain, misalnya jalankan /model opus dari sesi Sonnet, lalu tanyakan kepada Claude panduan apa yang dimilikinya tentang model saat ini.

Input PostModelSwitch

Hook PostModelSwitch menerima field yang sama seperti PreModelSwitch, dengan hook_event_name diatur ke "PostModelSwitch" dan dua nilai source tambahan: "auto" untuk fallback otomatis atau perubahan lain yang dilakukan Claude Code sendiri, dan "resume" untuk model yang dipulihkan saat Anda melanjutkan sesi.

requested_model bernilai null ketika source adalah "auto". Ketika source adalah "resume", nilainya adalah pengaturan model tersimpan yang dipulihkan Claude Code.

Kontrol keputusan PostModelSwitch

Claude Code mengambil stdout teks biasa hook Anda saat keluar dengan 0, atau additionalContext dari output JSON, dan mengirimkannya ke Claude bersama permintaan berikutnya setelah peralihan. Selain field output JSON yang tersedia untuk semua hook, Anda dapat mengembalikan:

Jika hook belum selesai dalam lima detik setelah Anda mengirim prompt berikutnya, Claude Code mengirim permintaan tersebut tanpa output dan melampirkannya ke permintaan setelahnya. Jika model berubah beberapa kali sebelum permintaan berikutnya, Claude Code hanya mengirimkan output untuk model target dari peralihan terakhir.

SessionEnd

Berjalan saat sesi Claude Code berakhir. Berguna untuk tugas pembersihan, mencatat statistik sesi, atau menyimpan status sesi. Mendukung matcher untuk memfilter berdasarkan alasan keluar.

Field reason dalam input hook menunjukkan mengapa sesi berakhir:

Input SessionEnd

Selain field input umum, hook SessionEnd menerima field reason yang menunjukkan mengapa sesi berakhir. Lihat tabel alasan 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"
}

Hook SessionEnd tidak memiliki kontrol keputusan. Hook ini tidak dapat memblokir penghentian sesi tetapi dapat melakukan tugas pembersihan. Claude Code membuang field output JSON hook ini, seperti systemMessage.

Hook SessionEnd memiliki timeout default 1,5 detik. Timeout ini berlaku saat Anda keluar, menjalankan /clear, atau beralih sesi dengan /resume interaktif. Anda dapat memberi hook lebih banyak waktu dengan dua cara:

• timeout per hook: atur timeout di konfigurasi hook tersebut. Anggaran keseluruhan naik secara otomatis untuk menyesuaikan dengan timeout per hook tertinggi di file pengaturan Anda, hingga 60 detik. Jika Anda menaikkan anggaran dengan cara ini, hook tanpa timeout sendiri tetap menggunakan default. Timeout yang diatur pada hook yang disediakan plugin tidak menaikkan anggaran.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS: atur environment variable ini dalam milidetik untuk menimpa anggaran secara eksplisit. Nilai yang Anda atur juga menjadi timeout untuk setiap hook tanpa timeout sendiri.

Contoh ini mengatur anggaran menjadi 5 detik:

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Sebelum v2.1.268, CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS hanya menaikkan anggaran keseluruhan, dan hook tanpa timeout sendiri tetap dibatalkan setelah 1,5 detik.

Elicitation

Berjalan saat server MCP meminta input pengguna di tengah tugas. Secara default, Claude Code menampilkan dialog interaktif agar pengguna merespons. Hook dapat mencegat permintaan ini dan merespons secara terprogram, melewati dialog sepenuhnya.

Field matcher dicocokkan dengan nama server MCP.

Input Elicitation

Selain field input umum, hook Elicitation menerima field mcp_server_name, message, serta field opsional mode, url, elicitation_id, dan requested_schema.

Untuk elicitation mode formulir, kasus yang 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 elicitation mode URL, yang 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"
}

Output Elicitation

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

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

Exit code 2 menolak elicitation. Claude Code tidak menampilkan pesan stderr Anda di mana pun.

Claude Code menindaklanjuti hookSpecificOutput dari output JSON hook Elicitation dan membuang systemMessage serta continue.

ElicitationResult

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

Field matcher dicocokkan dengan nama server MCP.

Input ElicitationResult

Selain field input umum, hook ElicitationResult menerima field mcp_server_name, action, serta field 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"
}

Output ElicitationResult

Untuk menimpa respons pengguna, kembalikan objek JSON dengan hookSpecificOutput:

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

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

Claude Code menindaklanjuti hookSpecificOutput dari output JSON hook ElicitationResult dan membuang systemMessage serta 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, secara default model yang digunakan Claude Code untuk fungsionalitas latar belakang
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.