Referensi hooks

Referensi untuk event hook Claude Code, skema konfigurasi, format JSON input/output, kode keluar, hooks asinkron, hooks HTTP, prompt hooks, dan MCP tool hooks.

[!TIP]

Untuk panduan quickstart dengan contoh, lihat Otomatisasi alur kerja dengan hooks.

Hooks adalah perintah shell yang ditentukan pengguna, endpoint HTTP, panggilan MCP tool, prompt LLM, atau subagent yang dijalankan secara otomatis pada titik-titik tertentu dalam siklus hidup Claude Code. Claude Code memicu event hook yang sama di mana pun ia berjalan: sesi di terminal, ekstensi IDE, aplikasi Desktop, dan sesi cloud. Gunakan referensi ini untuk mencari skema event, opsi konfigurasi, format JSON input/output, dan fitur lanjutan seperti async hooks, HTTP hooks, dan MCP tool hooks.

Plugin juga dapat mendaftarkan hook sebagai fungsi JavaScript yang dipanggil oleh Claude Code di dalam prosesnya sendiri, yang dapat menggambar di antarmuka sekaligus bertindak atas event. Plugin yang melakukan hal tersebut adalah sebuah mod, dan hook fungsi tersebut dibahas di Bereaksi terhadap event, bukan di sini. Hook di halaman ini tetap berfungsi berdampingan dengan mod.

Siklus hidup hook

Claude Code menjalankan hooks pada titik-titik tertentu selama sesi. Ketika event dijalankan dan matcher cocok, Claude Code meneruskan konteks JSON tentang event ke handler hook Anda. Untuk command hooks, input tiba di stdin. Untuk HTTP hooks, input tiba sebagai badan permintaan POST. Handler Anda kemudian dapat memeriksa input, mengambil tindakan, dan secara opsional mengembalikan keputusan.

Events jatuh ke dalam tiga cadence:

• per sesi: SessionStart dan SessionEnd
• per turn: UserPromptSubmit, Stop, dan StopFailure
• pada setiap pemanggilan tool di dalam loop agentic: PreToolUse dan PostToolUse, kecuali panggilan EndConversation, yang melewati keduanya

Tabel di bawah merangkum kapan setiap event dijalankan. Bagian Hook events mendokumentasikan skema input lengkap dan opsi kontrol keputusan untuk masing-masing.

Bagaimana hook diselesaikan

Untuk melihat bagaimana event, matcher, dan handler cocok bersama, pertimbangkan hook PreToolUse ini yang memblokir perintah shell yang merusak.

[tab] macOS/Linux

matcher mempersempit ke panggilan tool Bash dan perintah Monitor, dan kondisi if mempersempit lebih lanjut ke subperintah Bash yang cocok dengan rm *, jadi block-rm.sh hanya spawn ketika kedua filter cocok:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Skrip membaca input JSON dari stdin, mengekstrak perintah, dan mengembalikan permissionDecision dari "deny" jika berisi rm -rf. Simpan ke .claude/hooks/block-rm.sh di proyek Anda dan buat dapat dieksekusi dengan chmod +x .claude/hooks/block-rm.sh sehingga Claude Code dapat menjalankannya:

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # no decision; normal permission flow applies
fi

Skrip ini, seperti contoh Bash lainnya di halaman ini yang mengurai input JSON, menggunakan jq, jadi instal jq dan pastikan itu ada di PATH Anda sebelum mencobanya.

[tab] Windows (PowerShell)

Matcher Bash|PowerShell mencakup tool PowerShell serta Bash. Satu aturan if hanya menyebutkan satu tool, jadi setiap tool mendapat handler-nya sendiri: yang pertama mempersempit ke subperintah Bash yang cocok dengan rm *, yang kedua ke perintah PowerShell yang cocok dengan Remove-Item *. Keduanya menjalankan skrip yang sama melalui powershell.exe:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          }
        ]
      }
    ]
  }
}

Flag -NoProfile melewati pemuatan profil PowerShell Anda sehingga hook dimulai dengan cepat, dan -ExecutionPolicy Bypass memungkinkan PowerShell menjalankan file skrip lokal.

Skrip membaca input JSON dari stdin, mengekstrak perintah, dan mengembalikan permissionDecision dari "deny" jika berisi rm -rf atau Remove-Item diikuti oleh -Recurse. Simpan ke .claude/hooks/block-rm.ps1 di proyek Anda:

# .claude/hooks/block-rm.ps1
$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
$command = $callInput.tool_input.command

if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Destructive command blocked by hook"
    }
  } | ConvertTo-Json
} else {
  exit 0  # no decision; normal permission flow applies
}

Sekarang anggaplah Claude Code memutuskan untuk menjalankan Bash "rm -rf /tmp/build" terhadap konfigurasi macOS/Linux. Inilah yang terjadi:

1. Event dijalankan

Event PreToolUse dijalankan. Claude Code mengirimkan input tool sebagai JSON di stdin ke hook:

{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }

2. Matcher memeriksa

Matcher "Bash" cocok dengan nama tool, jadi grup hook ini diaktifkan. Jika Anda menghilangkan matcher atau menggunakan "*", grup diaktifkan pada setiap kemunculan event.

3. Kondisi if memeriksa

Kondisi if "Bash(rm *)" cocok karena rm -rf /tmp/build adalah subperintah yang cocok dengan rm *, jadi handler ini spawn. Jika perintah telah npm test, pemeriksaan if akan gagal dan block-rm.sh tidak akan pernah dijalankan, menghindari overhead spawn proses. Bidang if bersifat opsional; tanpanya, setiap handler dalam grup yang cocok dijalankan.

4. Handler hook dijalankan

Skrip memeriksa perintah lengkap dan menemukan rm -rf, jadi itu mencetak keputusan ke stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

Jika perintah telah menjadi varian rm yang lebih aman seperti rm file.txt, skrip akan mencapai exit 0 sebagai gantinya. Kode keluar 0 tanpa output berarti hook tidak memiliki keputusan untuk dilaporkan, jadi pemanggilan tool berlanjut melalui alur izin normal. Hook dapat menolak pemanggilan, tetapi tetap diam tidak menyetujuinya.

5. Claude Code bertindak atas hasil

Claude Code membaca keputusan JSON, memblokir pemanggilan tool, dan menunjukkan Claude alasannya.

Bagian Configuration di bawah mendokumentasikan skema lengkap, dan setiap bagian hook event mendokumentasikan input apa yang diterima perintah Anda dan output apa yang dapat dikembalikan.

Konfigurasi

Hooks didefinisikan dalam file pengaturan JSON. Konfigurasi memiliki tiga tingkat nesting:

1. Pilih hook event untuk merespons, seperti PreToolUse atau Stop
2. Tambahkan grup matcher untuk memfilter kapan hook dijalankan, seperti "untuk tool Bash"
3. Tentukan satu atau lebih hook handlers untuk dijalankan saat cocok

Lihat Bagaimana hook diselesaikan di atas untuk panduan lengkap dengan contoh beranotasi.

[!NOTE]

Halaman ini menggunakan istilah spesifik untuk setiap tingkat: hook event untuk titik siklus hidup, matcher group untuk filter, dan hook handler untuk perintah shell, endpoint HTTP, tool MCP, prompt, atau agent yang dijalankan. "Hook" sendiri merujuk pada fitur umum.

Lokasi hook

Tempat Anda mendefinisikan hook menentukan cakupannya:

Sesi cloud tidak membaca ~/.claude/settings.json lokal Anda. Dalam lingkungan self-hosted, Claude Code juga menjalankan hooks yang operator semai dari ~/.claude/ host runner, dan menjalankan hooks dalam file pengaturan terkelola image runner saat file itu termasuk dalam sumber terkelola yang Claude Code terapkan, yang secara default berarti hanya ketika pengaturan yang dikelola server maupun kebijakan Claude Code yang dikirimkan MDM tidak menyediakan tingkat terkelola. Lihat apa yang terbawa dari setup Anda untuk file pengaturan dan plugin mana, dan dengan demikian hooks mana, yang mencapai sesi cloud.

Untuk detail tentang resolusi file pengaturan, lihat settings.

Hooks dari file pengaturan, pengaturan kebijakan terkelola, dan plugin juga berjalan di dalam subagents. Ketika subagent memanggil tool, tool events seperti PreToolUse dan PostToolUse menjalankan hooks yang dikonfigurasi sama seperti dalam percakapan utama, dan input membawa field input umum agent_id dan agent_type yang mengidentifikasi subagent.

Administrator dapat menggunakan allowManagedHooksOnly dalam pengaturan terkelola untuk membatasi hooks mana yang berjalan:

• Hooks pengguna, proyek, lokal, dan plugin Anda diblokir. Hooks dari plugins yang dipaksa-aktifkan dalam pengaturan terkelola enabledPlugins dikecualikan
• Claude Code juga mempersempit pengaturan statusLine, fileSuggestion, dan subagentStatusLine Anda ke pengaturan terkelola
• Claude Code juga menonaktifkan plugins dengan sumber command, termasuk plugins yang dipaksa-aktifkan dalam pengaturan terkelola enabledPlugins, kecuali disableCommandPluginSources secara eksplisit diatur ke false. Sumber command memerlukan Claude Code v2.1.229 atau lebih baru
• Claude Code juga memblokir perintah headersHelper marketplace kecuali disableCommandPluginSources secara eksplisit diatur ke false, kecuali untuk marketplace yang pengaturan terkelola sendiri deklarasikan

Lihat apa yang berjalan di bawah allowManagedHooksOnly.

Hook entries bergabung di seluruh tingkat pengaturan daripada menggantikan satu sama lain: pengaturan pengguna, proyek, dan lokal menambahkan hooks mereka sendiri tanpa menghapus yang terkelola, dan pengaturan disableAllHooks tidak dapat menonaktifkan hooks terkelola dari luar pengaturan terkelola.

HTTP hook allowlists berlaku untuk hooks dari setiap sumber, termasuk pengaturan kebijakan terkelola:

• allowedHttpHookUrls: ketika didefinisikan di tingkat pengaturan apa pun, Claude Code menjalankan HTTP hook handler hanya jika URL-nya cocok dengan allowlist yang digabungkan
• httpHookAllowedEnvVars: ketika didefinisikan, Claude Code menginterpolasi hanya variabel lingkungan pada daftar itu ke dalam header hook

Pola matcher

Bidang matcher memfilter kapan hooks dijalankan. Bagaimana matcher dievaluasi tergantung pada karakter yang dikandungnya:

Matcher pada jalur ekspresi reguler diuji dengan RegExp.prototype.test JavaScript, yang berhasil pada kecocokan di mana pun dalam nilai. Edit.* cocok dengan Edit dan NotebookEdit; bungkus pola dalam ^ dan $, seperti ^Edit$, ketika Anda memerlukan kecocokan seluruh string.

FileChanged dan StopFailure menggunakan set exact-match yang lebih sempit dari huruf, digit, _, dan | saja. Tanda hubung, spasi, atau koma dalam matcher untuk dua event itu membuat tetap pada jalur ekspresi reguler, dan hanya | yang memisahkan alternatif. Setiap event lain dengan dukungan matcher dalam tabel yang mengikuti menerima | atau ,.

Event FileChanged tidak mengikuti aturan ini saat membangun daftar watch-nya. Lihat FileChanged.

Setiap tipe event cocok pada bidang yang berbeda:

Mencocokkan StopFailure pada cloud_credential_error memerlukan Claude Code v2.1.267 atau lebih baru, versi pertama yang melaporkan kegagalan pemuatan kredensial di bawah nilai itu daripada server_error atau unknown.

Untuk sebagian besar events, Claude Code mengevaluasi matcher terhadap bidang dari JSON input yang dikirimkan ke hook Anda di stdin. Untuk tool events, bidang itu adalah tool_name. Untuk PreModelSwitch dan PostModelSwitch, Claude Code mengevaluasi matcher terhadap nama kanonik yang diturunkan dari to_model, seperti dijelaskan di bawah PreModelSwitch. Setiap bagian hook event mencantumkan set lengkap nilai matcher dan skema input untuk event itu.

Contoh ini menjalankan skrip linting hanya ketika Claude menulis atau mengedit file:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Jika Anda menambahkan bidang matcher ke event tanpa dukungan matcher, itu diabaikan secara diam-diam.

Untuk tool events, Anda dapat memfilter lebih sempit dengan menetapkan bidang if pada handler hook individual. if menggunakan sintaks aturan izin untuk mencocokkan terhadap nama tool dan argumen bersama-sama, jadi "Bash(git *)" dijalankan ketika subperintah apa pun dari input Bash cocok dengan git * dan "Edit(*.ts)" dijalankan hanya untuk file TypeScript.

Cocokkan MCP tools

Tool server MCP muncul sebagai tool reguler dalam tool events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied), jadi Anda dapat mencocokkannya dengan cara yang sama seperti Anda mencocokkan nama tool lainnya.

MCP tools mengikuti pola penamaan mcp__<server>__<tool>, misalnya:

• mcp__memory__create_entities: tool create entities dari Memory server
• mcp__filesystem__read_file: tool read file dari Filesystem server
• mcp__github__search_repositories: tool search dari GitHub server

Untuk mencocokkan setiap tool dari server, tambahkan .* ke awalan server. .* diperlukan: matcher seperti mcp__memory atau mcp__brave-search hanya berisi karakter exact-match, jadi dibandingkan sebagai string yang tepat dan tidak cocok dengan tool apa pun.

• mcp__memory__.* cocok dengan semua tools dari server memory
• mcp__brave-search__.* cocok dengan semua tools dari server yang namanya berisi tanda hubung
• mcp__.*__write.* cocok dengan tool apa pun yang namanya dimulai dengan write dari server apa pun

Tools dari plugin-bundled MCP server menggunakan segmen server yang dibatasi yang mencakup nama plugin: mcp__plugin_<plugin-name>_<server-name>__<tool>. Matcher yang ditulis terhadap kunci server bare tidak pernah dijalankan untuk tools ini. Untuk plugin bernama my-plugin yang membundel server di bawah kunci db, tool query muncul sebagai mcp__plugin_my-plugin_db__query, jadi matcher untuk setiap tool dari server itu adalah mcp__plugin_my-plugin_db__.*. Gunakan nama tool yang dibatasi yang sama dalam bidang if handler. Lihat Plugin-provided MCP servers untuk bagaimana nama yang dibatasi dibangun.

Contoh ini mencatat semua operasi memory server dan memvalidasi operasi write dari server MCP apa pun:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

Cocokkan perintah Monitor

Hook PreToolUse atau PermissionRequest dengan matcher Bash juga berjalan pada perintah shell yang Claude mulai dengan tool Monitor, tetapi allow dan updatedInput-nya tidak berpengaruh pada perintah tersebut. Memerlukan Claude Code v2.1.314 atau lebih baru. Matcher seperti Bash|PowerShell, ^Bash$, dan Bash.* juga merupakan matcher Bash. Hook dengan matcher Bash tidak berjalan untuk WebSocket watch, dan hook PostToolUse dengan matcher tersebut tidak berjalan untuk Monitor.

Hook yang berjalan untuk perintah Monitor dapat menolaknya atau membuat Claude Code menanyakannya kepada Anda. Untuk mengizinkan atau menulis ulang perintah tersebut, beralihlah dari matcher Bash ke matcher yang menyertakan Monitor:

• Matcher yang menyertakan Monitor: dengan matcher seperti Bash|Monitor atau .*, atau tanpa matcher, hook mendapatkan input milik panggilan Monitor itu sendiri, dan allow serta updatedInput berlaku. Dalam if, sebutkan Monitor, seperti Monitor(tail *), yang mencocokkan berdasarkan aturan yang diikuti Bash(tail *). Jika if-nya menyebutkan Bash, hook tetap mendapatkan input panggilan Monitor, tetapi allow dan updatedInput tidak berpengaruh
• Matcher Bash: hook mendapatkan panggilan Bash. Dalam if, sebutkan Bash, seperti Bash(tail *). Hook tidak berjalan jika if-nya menyebutkan Monitor

Bidang hook handler

Setiap objek dalam array hooks inner adalah hook handler: perintah shell, endpoint HTTP, tool MCP, prompt LLM, atau agent yang dijalankan saat matcher cocok. Ada lima tipe:

• Command hooks (type: "command"): jalankan perintah shell. Skrip Anda menerima JSON input event di stdin dan mengkomunikasikan hasil kembali melalui kode keluar dan stdout.
• HTTP hooks (type: "http"): kirimkan JSON input event sebagai permintaan HTTP POST ke URL. Endpoint mengkomunikasikan hasil kembali melalui badan respons menggunakan format JSON output yang sama seperti command hooks.
• MCP tool hooks (type: "mcp_tool"): panggil tool pada server MCP yang dikonfigurasi. Output teks tool diperlakukan seperti command-hook stdout.
• Prompt hooks (type: "prompt"): kirimkan prompt ke model Claude untuk evaluasi single-turn. Model mengembalikan keputusannya sebagai JSON. Lihat Prompt-based hooks.
• Agent hooks (type: "agent"): spawn subagent yang dapat menggunakan tools seperti Read, Grep, dan Glob untuk memverifikasi kondisi sebelum mengembalikan keputusan. Agent hooks adalah eksperimental dan mungkin berubah. Lihat Agent-based hooks.

Ketika sebuah event dijalankan, hook yang cocok dengannya berjalan secara paralel. Jika lebih dari 12 di antaranya adalah prompt atau agent hook, 12 di antaranya berjalan sekaligus dan sisanya dimulai saat hook yang sedang berjalan selesai. timeout setiap hook yang menunggu mulai dihitung ketika hook tersebut dimulai.

Jika Anda mendefinisikan handler yang sama di lebih dari satu file pengaturan, itu berjalan sekali. Salinan handler yang sama dari plugin atau skill tetap terpisah.

Handlers berjalan di direktori saat ini dengan lingkungan Claude Code. Jika direktori saat ini tidak lagi ada, misalnya worktree atau direktori temp yang shell lain hapus di tengah-sesi, Claude Code menjalankan command hooks dari yang pertama dari ini yang masih ada: direktori tempat sesi dimulai, akar proyek, direktori home Anda, atau direktori temp sistem. Claude Code mencatat warning yang menamai direktori fallback dalam debug log. Untuk sesi worktree yang Anda mulai dari aplikasi desktop, lihat Apa yang dibagikan worktree dengan checkout utama.

Variabel lingkungan $CLAUDE_CODE_REMOTE adalah "true" di lingkungan web jarak jauh dan tidak diatur di CLI lokal. Claude Code v2.1.199 dan lebih baru menetapkan $CLAUDE_CODE_BRIDGE_SESSION_ID ke Remote Control session ID saat sesi lokal memiliki koneksi Remote Control yang aktif.

Bidang umum

Bidang-bidang ini berlaku untuk semua tipe hook:

Bidang if menyimpan tepat satu aturan izin. Tidak ada sintaks &&, ||, atau list untuk menggabungkan aturan; untuk menerapkan beberapa kondisi, tentukan handler hook terpisah untuk masing-masing.

Dalam kondisi if untuk file tool, pola direktori single-segment seperti "Edit(src/**)" cocok hanya dengan direktori src di direktori kerja dan file di bawahnya. Untuk mencocokkan direktori bernama src di kedalaman apa pun, tulis "Edit(**/src/**)".

Bagaimana pola if mencocokkan perintah Bash

Untuk pola Bash dalam bidang if, apakah hook command Anda dijalankan tergantung pada bentuk pola dan perintah Bash yang Claude panggil. Penugasan VAR=value terkemuka dihapus sebelum pencocokan.

Ketika Claude Code tidak dapat menentukan perintah mana yang dijalankan input Bash, itu menjalankan hook Anda terlepas dari pola. Karena filter if adalah best-effort, gunakan sistem izin daripada hook untuk memberlakukan allow atau deny yang keras.

Bidang command hook

Selain bidang umum, command hooks menerima bidang-bidang ini:

Exec form dan shell form

Hook command dijalankan sebagai exec form ketika args diatur, dan shell form ketika args dihilangkan. Atur args setiap kali hook mereferensikan path placeholder, karena setiap elemen dilewatkan sebagai satu argumen tanpa quoting. Hilangkan args ketika Anda memerlukan fitur shell seperti pipes atau &&, atau ketika tidak ada kekhawatiran yang berlaku.

Exec form dijalankan ketika args ada. Claude Code menyelesaikan command sebagai executable di PATH dan spawn-nya secara langsung dengan args sebagai vektor argumen. Tidak ada shell, jadi setiap elemen args adalah satu argumen persis seperti yang ditulis, dan path placeholders seperti ${CLAUDE_PLUGIN_ROOT} disubstitusi ke dalam command dan ke dalam setiap elemen args sebagai string biasa. Karakter khusus seperti apostrophe, $, dan backticks melewati verbatim karena tidak ada shell untuk menginterpretasinya. Tidak ada tokenisasi shell yang terjadi di platform apa pun.

Shell form dijalankan ketika args tidak ada. String command dilewatkan ke shell: sh -c di macOS dan Linux, Git Bash di Windows, atau PowerShell ketika Git Bash tidak diinstal. Atur bidang shell untuk memilih secara eksplisit. Shell melakukan tokenisasi string, memperluas variabel, dan menginterpretasi pipes, &&, redirects, dan globs.

[!NOTE]

Di Windows, exec form memerlukan command untuk diselesaikan ke executable nyata seperti .exe. Shim .cmd dan .bat yang npm, npx, eslint, dan tools lainnya instal di node_modules/.bin bukan executables dan tidak dapat di-spawn tanpa shell. Untuk menjalankannya dalam exec form, panggil skrip yang mendasar dengan node secara langsung, misalnya "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]. Pola node plus script-path bekerja di setiap platform karena node.exe adalah binary nyata. Untuk menjalankan shim .cmd atau .bat berdasarkan nama, gunakan shell form.

Contoh ini menjalankan skrip Node yang dibundel dengan plugin. Exec form melewatkan path skrip yang diselesaikan sebagai satu argumen tanpa quoting:

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
}

Shell form yang setara memerlukan quoting untuk menangani paths dengan spasi atau karakter khusus:

{
  "type": "command",
  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
}

Kedua form mendukung path placeholders yang sama, dan keduanya mengekspornya sebagai variabel lingkungan CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_ROOT, dan CLAUDE_PLUGIN_DATA pada proses yang di-spawn, jadi skrip dapat membaca process.env.CLAUDE_PLUGIN_ROOT terlepas dari bagaimana itu diluncurkan.

Plugin hooks juga mensubstitusi nilai ${user_config.*}, dalam exec form saja: nilai disubstitusi ke dalam command dan ke dalam setiap elemen args sebagai string biasa, jadi tidak ada shell yang mem-parse ulangnya.

Hook plugin bentuk shell yang command-nya mereferensikan ${user_config.*} gagal dengan error daripada menjalankan. Untuk menggunakan nilai opsi dari hook bentuk shell, baca variabel lingkungan $CLAUDE_PLUGIN_OPTION_<KEY>, seperti $CLAUDE_PLUGIN_OPTION_WEBHOOK_URL untuk opsi webhook_url, atau atur args untuk beralih hook ke exec form. Sebelum v2.1.207, hook plugin bentuk shell juga mensubstitusi ${user_config.*}.

[!NOTE]

Dalam exec form, command adalah nama executable atau path saja. Jika command adalah nama bare tanpa path separator dan berisi whitespace bersama args, Claude Code mencatat warning karena spawn akan gagal: tidak ada executable bernama node script.js. Pindahkan token ekstra ke dalam args. Path absolut dengan spasi, seperti C:\Program Files\nodejs\node.exe, adalah executable tunggal yang valid dan tidak memicu warning.

Bidang HTTP hook

Selain bidang umum, HTTP hooks menerima bidang-bidang ini:

Claude Code mengirimkan JSON input hook sebagai badan permintaan POST dengan Content-Type: application/json. Badan respons menggunakan format JSON output yang sama seperti command hooks.

Penanganan kesalahan berbeda dari command hooks; lihat HTTP response handling.

Contoh ini mengirimkan event PreToolUse ke layanan validasi lokal, mengautentikasi dengan token dari variabel lingkungan MY_TOKEN:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Bidang MCP tool hook

Selain bidang umum, MCP tool hooks menerima bidang-bidang ini:

Contoh ini memanggil tool security_scan pada server MCP my_server setelah setiap Write atau Edit, melewatkan path file yang diedit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": { "file_path": "${tool_input.file_path}" }
          }
        ]
      }
    ]
  }
}

Bagaimana hasil tool dibaca

Claude Code membaca konten teks tool dengan cara yang sama seperti membaca command-hook stdout, mengikuti aturan parsing di bawah exit code 0. Jika tool mengembalikan isError: true, hook menghasilkan kesalahan non-blocking dan eksekusi berlanjut.

Ketika server masih dalam proses terhubung

Pada event di mana hook dapat memblokir atau mengubah hasil, seperti PreToolUse atau Stop, Claude Code menunggu server yang sedang terhubung sebelum memanggil tool, paling lama MCP_TIMEOUT dan dalam batas timeout milik hook itu sendiri. Pada event observasional, seperti Notification atau SessionEnd, Claude Code tidak menunggu.

Server yang menampilkan status cached terhubung ketika hook memanggil tool-nya. Jika server belum terhubung pada saat itu, hook menghasilkan kesalahan non-blocking dan eksekusi berlanjut. Hook tidak pernah memulai alur OAuth, jadi autentikasi server dari /mcp terlebih dahulu.

Event yang dijalankan sebelum server MCP tersedia

SessionStart saat peluncuran, termasuk dengan --continue atau --resume, dan setiap event Setup dijalankan sebelum server MCP sesi tersedia untuk hook. Claude Code melewatkan hook mcp_tool mereka tanpa memanggil tool, dan debug log mencatat mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context), atau pesan yang sama yang menyebut Setup. Ketika SessionStart dijalankan lagi nanti dalam sesi, setelah /clear atau compaction, hook mcp_tool-nya berjalan. Untuk apa pun yang dibutuhkan sesi saat peluncuran, gunakan hook type: "command" pada SessionStart sebagai gantinya.

Bidang prompt dan agent hook

Selain bidang umum, prompt dan agent hooks menerima bidang-bidang ini:

Referensi skrip berdasarkan path

Gunakan placeholders ini untuk mereferensikan skrip hook relatif terhadap akar proyek atau plugin, terlepas dari direktori kerja saat hook dijalankan:

• ${CLAUDE_PROJECT_DIR}: akar proyek tempat sesi dimulai. Claude Code juga menetapkan variabel ini dalam lingkungan stdio MCP servers dan plugin LSP servers.
• ${CLAUDE_PLUGIN_ROOT}: direktori instalasi plugin, untuk skrip yang dibundel dengan plugin. Lihat plugin environment variables untuk bagaimana path berperilaku di seluruh pembaruan.
• ${CLAUDE_PLUGIN_DATA}: direktori data persisten plugin, untuk dependensi dan status yang harus bertahan pembaruan plugin.

[!NOTE]

Worktrees berbeda. Jika Claude memasuki worktree selama sesi, Claude Code menyimpan ${CLAUDE_PROJECT_DIR} di mana itu berada dan melewatkan path worktree ke hooks Anda dengan cara berbeda:

• ${CLAUDE_PROJECT_DIR} tetap di tempat: itu masih menunjuk ke akar proyek tempat sesi dimulai, jadi perintah seperti ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh masih menjalankan skrip di checkout utama.
• cwd mengikuti Claude: bidang cwd dalam input JSON hook adalah akar worktree setelah Claude memasuki worktree, dan direktori baru setelah Claude menjalankan cd. Bacanya ketika hook perlu tahu direktori mana Claude sedang bekerja.

Untuk sesi worktree yang Anda mulai dari aplikasi desktop, lihat Apa yang dibagikan worktree dengan checkout utama untuk mengetahui ke mana ${CLAUDE_PROJECT_DIR} menunjuk.

Lebih suka exec form untuk hook apa pun yang mereferensikan path placeholder. Dalam shell form, bungkus setiap placeholder dalam tanda kutip ganda.

[tab] Skrip proyek

Contoh ini menggunakan ${CLAUDE_PROJECT_DIR} untuk menjalankan pemeriksa gaya dari direktori .claude/hooks/ proyek setelah pemanggilan tool Write atau Edit apa pun:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

[tab] Skrip plugin

Tentukan plugin hooks dalam hooks/hooks.json dengan bidang description tingkat atas opsional. Ketika plugin diaktifkan, hooks-nya bergabung dengan hooks pengguna dan proyek Anda.

Contoh ini menjalankan skrip pemformatan yang dibundel dengan plugin:

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Lihat plugin components reference untuk detail tentang membuat plugin hooks.

Hooks dalam skills dan agents

Selain file pengaturan dan plugin, hooks dapat didefinisikan langsung dalam skills dan subagents menggunakan frontmatter, dalam format konfigurasi yang sama seperti hooks berbasis pengaturan. Berapa lama Claude Code menyimpannya terdaftar tergantung pada komponen:

• Subagent hooks: Claude Code menjalankannya hanya saat subagent itu berjalan dan menghapusnya saat selesai. Claude Code mengkonversi hook Stop di sini menjadi SubagentStop, event yang dijalankan saat subagent selesai.
• Skill hooks: Claude Code mendaftarkannya ketika Anda atau Claude memanggil skill dan terus menjalankannya untuk sisa sesi, pada turns setelah turn skill sendiri juga. Untuk membuat Claude Code menghapus hook setelah run pertamanya yang berhasil, atur once: true padanya.

Skill ini mendefinisikan hook PreToolUse yang menjalankan skrip validasi keamanan sebelum setiap perintah Bash:

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Subagents menggunakan format yang sama dalam frontmatter YAML mereka.

Frontmatter hooks dalam skill proyek mengikuti workspace trust rule yang sama seperti hooks dalam file pengaturan. Claude Code mendaftarkannya ketika Anda atau Claude memanggil skill, termasuk dalam run -p dalam folder yang belum Anda percayai.

Frontmatter hooks dalam subagent proyek berjalan hanya setelah Anda menerima workspace trust dialog untuk folder asal file agent tersebut. Sesi -p tidak dihitung sebagai menerimanya. Apa yang berjalan sebelum Anda mempercayai folder membandingkan ini dengan rule file pengaturan, dan halaman subagents mencantumkan cakupan mana yang dikecualikan.

Batasan pada hook skill

Ketika hook frontmatter sebuah skill tidak dijalankan setelah Anda atau Claude memanggil skill tersebut, jalankan /hooks dalam sesi itu. Jika menu itu mencantumkannya, lihat Hook tidak dijalankan. Jika tidak satu pun tercantum, skill tersebut mungkin berada di bawah penguncian khusus plugin atau telah melewati batas hook, dan berjalan tanpa satu pun hook frontmatter-nya. Periksa setiap kasus:

• Penguncian khusus plugin: administrator organisasi Anda dapat mengunci hooks ke plugin dan pengaturan terkelola dengan pengaturan terkelola strictPluginOnlyCustomization. Sebuah skill mempertahankan hook frontmatter-nya di bawah penguncian tersebut hanya jika skill itu adalah skill plugin, skill bawaan, atau skill di direktori pengaturan terkelola. Hook dalam file pengaturan Anda sendiri juga tidak berjalan.
  • Periksa: ketik /status dalam sesi Claude Code. Jika baris Setting sources mencakup Enterprise managed settings, tanyakan kepada administrator Anda apakah strictPluginOnlyCustomization mengunci hooks.
  • Perbaiki: pindahkan skill ke dalam plugin, karena skill plugin mempertahankan hook frontmatter-nya. Cantumkan plugin tersebut di marketplace, lalu instal dari sana. Jika Claude Code menolak marketplace dengan is blocked by enterprise policy, minta administrator Anda untuk mengizinkan marketplace tersebut.
• Batas hook: di Claude Code v2.1.304 atau lebih baru, setiap sumber skill memiliki batasnya sendiri per sesi. Proyek Anda, folder skill pribadi Anda, dan setiap plugin dihitung sebagai sumber terpisah. Skill dari satu sumber dapat mendaftarkan paling banyak 1.024 hook. Matcher dari hook-hook tersebut dapat berjumlah total paling banyak 16.384 karakter. Matcher dengan beberapa hook di bawahnya dihitung satu kali untuk setiap hook.
  • Periksa: ulangi sesi tempat hook tidak dijalankan, dengan debug logging aktif:
    1. Mulai sesi baru dari shell Anda dengan claude --debug. Jika Anda tidak memulai sesi dari shell, ketik /debug terlebih dahulu di sesi baru sebagai gantinya.
    2. Panggil skill yang sama dalam urutan yang sama, termasuk yang dipanggil Claude, karena kedua total bertambah skill demi skill. Minta Claude untuk memanggil skill apa pun yang tidak dapat Anda ketik sebagai perintah.
    3. Cari registers none of its hooks di debug log. Baris yang berisi teks tersebut menyebutkan skill yang melewati batas.
  • Perbaiki: deklarasikan lebih sedikit hook atau matcher yang lebih pendek di skill tersebut atau di skill lain dari sumbernya, lalu mulai sesi baru. Jika skill tersebut bukan milik Anda untuk diedit, minta pembuatnya untuk melakukan perubahan itu. Sampai saat itu, mulai sesi baru dan panggil skill yang Anda butuhkan sebelum skill lain dari sumbernya.

Jika tidak ada kasus yang sesuai dengan situasi Anda, periksa frontmatter yang tidak berhasil di-parse.

Menu /hooks

Ketik /hooks di Claude Code untuk membuka browser read-only untuk hooks yang telah Anda konfigurasi. Daftar memberi label pada setiap hook dengan asalnya, seperti pengaturan pengguna, pengaturan proyek, pengaturan lokal, plugin, atau sesi saat ini.

Pilih hook untuk melihat teks lengkap dari apa yang dijalankannya dan di mana hook itu didefinisikan, seperti path file pengaturannya atau nama plugin-nya.

Untuk menelusuri semua hook event, termasuk yang tidak memiliki hooks yang dikonfigurasi, pilih All events di akhir daftar.

Nonaktifkan atau hapus hooks

Untuk menghapus hook yang didefinisikan dalam file pengaturan, hapus entrinya dari file tersebut.

Untuk menonaktifkan semua hooks sementara tanpa menghapusnya, atur "disableAllHooks": true dalam file pengaturan Anda. Claude Code membaca nilai yang tersisa setelah settings precedence diterapkan, jadi "disableAllHooks": false dalam .claude/settings.json proyek menimpa true dalam pengaturan pengguna Anda. Untuk mematikan hooks untuk satu run apa pun yang dikatakan pengaturan proyek, lewatkan --settings '{"disableAllHooks": true}', yang mengambil prioritas atas pengaturan proyek dan lokal. Tidak ada cara untuk menonaktifkan hook individual sambil menyimpannya dalam konfigurasi.

Pengaturan disableAllHooks menghormati hierarki pengaturan terkelola. Jika administrator telah mengonfigurasi hooks melalui pengaturan kebijakan terkelola, disableAllHooks yang diatur dalam pengaturan pengguna, proyek, atau lokal tidak dapat menonaktifkan hooks terkelola tersebut. Hanya disableAllHooks yang diatur pada tingkat pengaturan terkelola yang dapat menonaktifkan hooks terkelola. Untuk jangkauan lengkap setiap tingkat, lihat disableAllHooks.

Pengeditan langsung ke hooks dalam file pengaturan biasanya diambil secara otomatis oleh file watcher.

Input dan output hook

Hook perintah menerima data JSON melalui stdin dan menyampaikan hasil melalui exit code, stdout, dan stderr. Hook HTTP menerima JSON yang sama sebagai body permintaan POST dan menyampaikan hasil melalui body respons HTTP. Bagian ini membahas field dan perilaku yang umum untuk semua event. Bagian setiap event di bawah Event hook mencakup skema input spesifik dan opsi kontrol keputusannya.

Di macOS dan Linux, hook perintah berjalan dalam sesinya sendiri tanpa terminal pengendali. Proses hook dan proses turunannya tidak dapat membuka /dev/tty atau mengirim escape sequence secara langsung ke antarmuka Claude Code. Windows tidak memiliki /dev/tty.

Untuk menampilkan pesan kepada pengguna di platform apa pun, kembalikan systemMessage dalam output JSON. Beberapa event membuangnya atau mengirimkannya ke tempat lain, dan bagian setiap event menyebutkannya. Untuk memicu notifikasi desktop, mengatur judul jendela, atau membunyikan bel, kembalikan terminalSequence sebagai gantinya.

Field input umum

Event hook menerima field berikut sebagai JSON, selain field khusus event yang didokumentasikan di setiap bagian event hook. Untuk hook perintah, JSON ini tiba melalui stdin. Untuk hook HTTP, JSON ini tiba sebagai body permintaan POST.

agent_id dan agent_type memberi tahu skrip Anda di agent mana hook dijalankan, seperti subagent, rekan tim in-process, atau agent yang Anda pilih dengan --agent:

Hanya hook SessionStart yang dapat menerima field model, dan Claude Code tidak selalu menyertakannya. Hook PreModelSwitch dan PostModelSwitch menerima from_model dan to_model sebagai gantinya, jadi gunakan hook PostModelSwitch untuk mengikuti model saat model berubah selama sesi.

Tidak ada environment variable $CLAUDE_MODEL. Hook dapat membaca $ANTHROPIC_MODEL jika Anda mengaturnya di shell Anda, tetapi nilai tersebut tidak berubah ketika Anda mengganti model dengan /model selama sesi.

Proses hook mewarisi environment induk, kecuali variabel exporter OTEL_* yang dihapus Claude Code dari setiap subproses yang dijalankannya dan, ketika CLAUDE_CODE_SUBPROCESS_ENV_SCRUB diatur ke 1, variabel-variabel yang dihapusnya. Dalam sesi yang mendapatkan konfigurasi HIPAA, Claude Code juga menghapus kredensial Anthropic dari environment hook.

Misalnya, hook PreToolUse untuk perintah Bash menerima ini di stdin:

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

Field tool_name, tool_input, dan tool_use_id bersifat khusus event. Setiap bagian event hook mendokumentasikan field tambahan untuk event tersebut.

Output exit code

Ketika eksekusi hook Anda selesai, Claude Code menggunakan exit code-nya untuk memutuskan apakah akan melanjutkan tindakan yang memicunya, seperti panggilan tool atau prompt:

• Berhasil: hook Anda keluar dengan 0. Claude Code menerapkan field output JSON apa pun yang dicetak hook Anda, dan tindakan dilanjutkan kecuali field tersebut memblokir atau menolaknya. Hook yang memulai proses latar belakang membahas pengecualiannya.
• Error blocking: hook Anda keluar dengan 2. Pada event yang dapat memblokir, Claude Code menghentikan tindakan.
• Error non-blocking: hook Anda keluar dengan kode lain, atau gagal dengan cara lain, seperti tidak dapat dimulai atau mencetak JSON yang tidak valid. Tindakan dilanjutkan, kecuali untuk hook yang kegagalannya memblokir tindakan, misalnya hook dengan onFailure diatur ke "block". Pada event seperti PreToolUse, Anda melihat pemberitahuan <hook name> hook error di transkrip.

Apa yang dicetak hook Anda ke stdout dapat mengubah hasilnya. Misalnya, ketika hook PreToolUse keluar dengan 1 tetapi mencetak JSON yang lolos validasi, JSON tersebut tetap dapat menentukan apa yang terjadi. Untuk menemukan hasil hook Anda pada event seperti PreToolUse, cocokkan apa yang dicetaknya ke stdout di kolom pertama dengan exit code-nya di bagian atas:

Beberapa event memiliki aturannya sendiri:

• WorktreeCreate: exit code bukan nol apa pun membuat pembuatan worktree gagal, apa pun isi JSON Anda.
• WorktreeRemove: exit code bukan nol apa pun membuat penghapusan worktree gagal jika direktori masih ada setelahnya.
• Stop, SubagentStop, TaskCompleted, dan hook UserPromptSubmit dari plugin: ketika hook Anda keluar dengan 2 tanpa apa pun di stdout dan stderr-nya menyatakan bahwa suatu file tidak ada, seperti No such file or directory, Claude Code memperlakukan eksekusi tersebut sebagai error non-blocking.
• Elicitation dan ElicitationResult: Claude Code menerapkan hookSpecificOutput Anda ketika hook Anda keluar dengan 0, dan mengabaikannya pada exit code lainnya.
• Event yang membuang output hook, seperti StopFailure: Claude Code mengabaikan JSON Anda pada setiap exit code, kecuali field efek samping seperti terminalSequence, yang tetap dijalankan.

Untuk memeriksa apa yang dilakukan exit code 2 pada event Anda, lihat Perilaku exit code 2 per event. Untuk memeriksa field keputusan mana yang dihormatinya, lihat Kontrol keputusan.

Exit code 0

Exit 0 berarti berhasil, dan merupakan exit code yang dimaksudkan ketika Anda mencetak JSON untuk kontrol terstruktur. Ketika hook Anda keluar dengan 0 tetapi mencetak JSON yang tidak dapat di-parse atau gagal validasi skema, tindakan dilanjutkan kecuali hook tersebut adalah hook yang kegagalannya memblokir tindakan. Alih-alih berhasil dengan field Anda diterapkan, eksekusi tersebut menjadi error non-blocking.

Untuk memperbaiki output Anda, gunakan pesan parse atau validasi yang dimuat oleh pemberitahuan <hook name> hook error. Untuk hook yang tidak async, stdout Anda dihitung sebagai output JSON hanya ketika Anda mencetak satu objek JSON, dalam satu baris atau beberapa baris, tanpa apa pun di sekitarnya selain whitespace. Claude Code membaca stdout lainnya sebagai teks biasa atau kegagalan parse:

• Output yang tidak diawali dengan {, atau yang diawali dengan { tetapi tidak diakhiri dengan }: teks biasa. Array JSON dan string JSON yang diberi tanda kutip merupakan teks biasa menurut aturan ini.
• Dua baris atau lebih yang masing-masing dapat di-parse sebagai JSON secara terpisah, dengan baris pertama diawali { dan baris terakhir diakhiri }: teks biasa ketika tidak ada baris yang merupakan objek output JSON yang mengatur suatu field. Ketika ada baris yang demikian, output tersebut adalah kegagalan parse, jadi cetak objek tersebut tanpa apa pun lainnya di stdout.
• Apa pun lainnya yang diawali dengan { dan diakhiri dengan } tetapi bukan JSON yang valid: kegagalan parse.

Untuk sebagian besar event, Claude Code menulis stdout ke log debug dan tidak menampilkannya di transkrip. Pada event berikut, stdout Anda sampai ke Claude atau ke ringkasan compaction:

• UserPromptSubmit, UserPromptExpansion, SessionStart, dan PostModelSwitch: Claude Code menambahkan stdout teks biasa sebagai konteks yang dapat dilihat dan ditindaklanjuti oleh Claude. Claude Code tidak menambahkan stdout yang gagal di-parse.
• PreCompact: stdout Anda menjadi instruksi untuk ringkasan compaction

Claude tidak pernah melihat stderr dari hook yang keluar dengan 0. Untuk membacanya sendiri pada event seperti PreToolUse, aktifkan logging debug. Untuk menyampaikan peringatan kepada Claude dari hook PostToolUse atau PostToolUseFailure, gunakan exit 2 sehingga Claude melihat stderr meskipun tool sudah berjalan.

Exit code 2

Keluar dengan kode 2 untuk memblokir tindakan. Pada event yang dapat memblokir, Claude Code menghentikan tindakan: misalnya, hook PreToolUse memblokir panggilan tool, dan hook UserPromptSubmit menolak prompt.

Pesan yang menyertai pemblokiran adalah stderr hook Anda. Jika hook Anda juga mencetak JSON yang membuat keputusan pemblokiran, Claude Code menggunakan alasan dari keputusan tersebut sebagai gantinya.

Exit 2 memblokir bahkan ketika hook Anda mencetak JSON:

• JSON yang lolos validasi skema: Claude Code tetap membaca field output JSON, tetapi field tersebut tidak dapat menimpa pemblokiran. Bahkan permissionDecision bernilai "allow" tidak membuat tindakan diloloskan. Pada Elicitation dan ElicitationResult, hookSpecificOutput dari hook yang keluar dengan exit 2 diabaikan.
• JSON yang gagal validasi skema: hook tetap memblokir. Claude Code menggunakan stderr Anda sebagai alasan pemblokiran dan mencatat kegagalan validasi di log debug.

Skrip ini memblokir perintah rm dengan keluar menggunakan 2 dan menyerahkan setiap perintah lain ke alur izin normal:

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

Dengan skrip ini terdaftar sebagai hook PreToolUse pada Bash, perintah yang diawali dengan rm diblokir, dan Claude menerima stderr hook sebagai error tool, dengan awalan nama event, nama tool, dan perintah hook:

PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed

Exit code lainnya

Pemberitahuan <hook name> hook error dengan Failed with non-blocking status code: berarti exit code hook Anda bukan 0 atau 2 dan stdout-nya berupa teks biasa atau kosong. Kecuali hook tersebut adalah hook yang kegagalannya memblokir tindakan, ini adalah error non-blocking, sehingga hook Anda tidak menghentikan tindakan. Untuk menangkap stderr lengkap hook Anda alih-alih hanya baris pertama yang ditampilkan pemberitahuan, aktifkan logging debug.

Misalnya, ketika hook PreToolUse pada Bash mencetak something broke ke stderr dan keluar dengan 1, pemberitahuan PreToolUse:Bash hook error memuat baris ini:

Failed with non-blocking status code: something broke

Jika pemberitahuan memuat pesan No such file or directory dari shell, seperti pada baris berikut, hook tidak pernah berjalan, misalnya karena path skripnya tidak ada:

Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory

Jika path-nya salah, perbaiki di tempat hook dikonfigurasi. Dalam bentuk shell, ketika path skrip tidak ada atau tidak dapat dieksekusi, shell keluar dengan kode seperti 127 dan pemberitahuan memuat pesan interpreter. Kecuali hook tersebut adalah hook yang kegagalannya memblokir tindakan, hook yang tidak dapat dimulai juga merupakan error non-blocking.

Saat Anda menyiapkan hook kebijakan, perhatikan pemberitahuan ini pada eksekusi pertamanya, karena path yang salah ketik di settings.json berarti hook tidak pernah berjalan. Untuk memblokir tindakan ketika hook tidak dapat dimulai, atur onFailure: "block".

[!WARNING]

Exit code 1 tanpa output JSON yang valid adalah error non-blocking kecuali hook tersebut adalah hook yang kegagalannya memblokir tindakan, meskipun 1 adalah kode kegagalan Unix yang konvensional. Jika hook Anda dimaksudkan untuk menegakkan kebijakan, gunakan exit 2.

Timeout

Selain hook perintah yang Anda jalankan dengan async: true, Claude Code membatalkan hook command, http, atau mcp_tool yang mencapai timeout-nya, membuang output hook, sehingga pada sebagian besar event hook yang mengalami timeout tidak memberikan keputusan. Pada PreModelSwitch, hook yang dibatalkan karena timeout memblokir pergantian model.

Pada PreToolUse, hook command, http, atau mcp_tool yang mengalami timeout tidak memblokir panggilan tool, kecuali untuk hook yang kegagalannya memblokir tindakan. Panggilan berlanjut melalui alur izin normal, jadi jangan mengandalkan hook yang macet untuk berfungsi sebagai gerbang. Untuk memblokir panggilan ketika hook command atau http mengalami timeout, atur onFailure: "block". Callback hook Agent SDK yang melebihi timeout-nya memblokir panggilan tool.

Hook yang memulai proses latar belakang

Jika hook perintah Anda membuat keputusannya dalam proses latar belakang lalu keluar, penolakan yang dicetak proses tersebut setelah Claude Code berhenti membaca tidak memblokir panggilan tool. Untuk hook yang tidak async, Claude Code selesai membaca output hook sesaat setelah proses hook itu sendiri keluar.

Cetak keputusan sebelum Anda memulai proses latar belakang, dan alihkan stdout dan stderr proses tersebut. Jika skrip Anda mencetak allow, lalu memulai proses latar belakang tanpa mengalihkan stdout dan stderr proses tersebut, Claude Code memblokir panggilan tool. Error hook menyertakan refusing to honor the suspect capture.

Skrip hook PreToolUse ini mencetak keputusan dengan policy-check.sh, lalu mengunggah metrik di latar belakang:

#!/bin/bash
"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $?
"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 &

Bagian lain dari skrip melakukan hal berikut:

• || exit $?: menjadikan exit code pemeriksaan sebagai exit code hook itu sendiri, sehingga pemeriksaan yang keluar dengan 2 untuk menolak tetap memblokir. Jika tidak, hook keluar dengan kode dari baris terakhir, yaitu 0.
• >/dev/null 2>&1 &: menjalankan upload-metrics.sh di latar belakang dengan output yang dialihkan, sehingga proses tersebut tidak membuat output hook tetap terbuka.

Untuk menguji skrip, buat policy-check.sh keluar dengan 2, lalu picu panggilan tool yang cocok dengan hook. Panggilan tool diblokir.

Memblokir tindakan ketika hook gagal

Pada sebagian besar event, ketika hook gagal atau mengalami timeout, Claude Code tetap menjalankan tindakan. Hook kebijakan dengan path yang salah atau skrip yang crash kemudian meloloskan semuanya. Untuk memblokir tindakan sebagai gantinya, atur "onFailure": "block" pada hook command atau http. Memerlukan Claude Code v2.1.295 atau lebih baru. Untuk callback hook Agent SDK, lihat Memblokir tindakan ketika callback gagal.

[!NOTE]

Di Windows tanpa Git Bash, hook perintah PreToolUse atau PermissionRequest berbentuk shell yang gagal dengan onFailure tidak diatur dapat memblokir panggilan tool sebagai gantinya.

Hook PreToolUse di .claude/settings.json ini menjalankan skrip proyek sebelum setiap perintah Bash, dan memblokir perintah jika skrip gagal:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

Untuk mengujinya, biarkan check-command.js tidak ada dan minta Claude menjalankan perintah Bash seperti ls. Claude Code memblokir panggilan, dan error-nya menyertakan failed; blocking because onFailure is "block" diikuti output error node itu sendiri, yang dipangkas di sini menjadi satu baris:

PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'

Setelah timeout, pesan menyatakan timed out alih-alih failed. Tanpa onFailure diatur, skrip yang sama yang tidak ada adalah error non-blocking dan ls berjalan.

Setiap hal berikut dihitung sebagai kegagalan:

• Tidak dapat dimulai: hook perintah gagal dimulai, misalnya karena skrip atau executable tidak ada
• Exit code selain 0 atau 2: berlaku untuk hook perintah meskipun hook tersebut mencetak JSON yang mengizinkan tindakan, seperti permissionDecision: "allow". Untuk mengembalikan keputusan JSON, keluar dengan 0
• Error HTTP: koneksi hook HTTP gagal, atau status respons bukan 2xx
• Timeout: hook mencapai timeout-nya
• Output tidak valid: output JSON tidak dapat di-parse atau gagal validasi skema. Untuk hook HTTP, body 2xx yang bukan kosong dan bukan objek JSON juga dihitung. Stdout teks biasa dari hook perintah bukan kegagalan

Dengan "block" diatur, kegagalan melakukan apa yang dilakukan exit code 2 pada event tersebut, kecuali pada PermissionRequest, di mana kegagalan menolak permintaan. Misalnya, kegagalan PreToolUse memblokir panggilan tool dan kegagalan UserPromptSubmit memblokir prompt.

Field ini tidak berpengaruh pada hook berikut:

• Hook Stop, SubagentStop, TaskCompleted, dan TeammateIdle: exit code 2 pada event ini mengirim Claude kembali untuk terus bekerja, dan Claude tidak dapat memperbaiki hook yang tidak mau berjalan
• Hook perintah latar belakang: hook perintah yang mengatur async atau asyncRewake

Hook yang gagal di Windows tanpa Git Bash

Jika error untuk panggilan tool yang diblokir menyertakan teks ini, hook perintah PreToolUse atau PermissionRequest gagal atau mengalami timeout dan memblokir panggilan tersebut:

blocking because Git Bash wasn't found, so only exit code 0 or 2 counts as this hook's verdict.

Jika error juga menyatakan PowerShell started no program, mulailah dengan perbaikan untuk command yang hanya berisi string bertanda kutip, yang dicetak PowerShell alih-alih dijalankan.

Tanpa Git Bash, exit code apa pun selain 0 atau 2 dari hook tersebut dihitung sebagai kegagalan, bahkan ketika hook mencetak JSON yang tidak menolak panggilan. Untuk mengetahui mengapa hook gagal, periksa log debug. Lalu pilih perbaikan yang sesuai dengan hook Anda:

• Panggilan sebaiknya dilanjutkan ketika hook gagal: tambahkan "onFailure": "continue" ke hook
• Hook keluar dengan 1 untuk memberi peringatan tetapi harus memblokir ketika crash: dengan "onFailure": "continue", panggilan dilanjutkan pada exit code 1, baik itu peringatan maupun crash. Tambahkan "onFailure": "block" sebagai gantinya, dan akhiri skrip dengan exit code 0 di bagian yang memberi peringatan, sehingga panggilan tersebut dilanjutkan. Untuk tetap menampilkan peringatan pada PreToolUse, cetak peringatan ke stdout sebagai field systemMessage dari satu objek JSON.
• Hook ditulis untuk Bash: tanpa Git Bash, hook berbentuk shell tanpa shell yang diatur berjalan di PowerShell, tempat hook tersebut dapat gagal. Instal Git for Windows, atau atur CLAUDE_CODE_GIT_BASH_PATH jika Git Bash terinstal di lokasi yang tidak ditemukan Claude Code. Lalu mulai sesi baru.
• Hook menjalankan satu .exe, bukan file .cmd atau .bat: letakkan program di command dan argumennya di args untuk menggunakan bentuk exec, lalu tambahkan "onFailure": "block". Claude Code kemudian memulai program tanpa shell. Tanpa "onFailure": "block", panggilan dapat dilanjutkan ketika program gagal, tidak ada, atau mengalami timeout
• Hook penjaga PowerShell yang harus memblokir saat gagal: dengan onFailure tidak diatur, hook ini berhenti memblokir setelah Git for Windows terinstal dan Claude Code menemukan Git Bash. Tambahkan "onFailure": "block" sehingga kegagalan atau timeout memblokir panggilan dengan atau tanpa Git Bash. Atur juga "shell": "powershell" sehingga hook tetap berjalan di PowerShell sejak saat itu alih-alih di Git Bash

Sebelum v2.1.309, pesannya berbunyi blocking because Git Bash wasn't found and this hook doesn't set "shell" to "powershell", so only exit code 0 or 2 counts as its verdict.

PowerShell started no program

Hook dengan error ini berjalan di PowerShell, yang mencetak command yang hanya berisi string bertanda kutip, seperti "command": "\"C:\\Tools\\guard.exe\"", alih-alih menjalankannya.

• Untuk mencetak teks, seperti JSON: atur "shell": "powershell", dan hook keluar dengan 0
• Untuk menjalankan file .ps1, .cmd, atau .bat, atau .exe yang path-nya memiliki variabel: atur "shell": "powershell" dan letakkan & sebelum path yang diberi tanda kutip. Biarkan $HOME seperti yang tertulis, dan tuliskan environment variable seperti contoh check.ps1 menuliskan $env:CLAUDE_PROJECT_DIR
• Untuk menjalankan satu .exe pada path tanpa $: hapus tanda kutip bagian dalam dari command, lalu terapkan perbaikan untuk hook yang menjalankan satu .exe, dengan menulis "args": [] jika program tidak menerima argumen
• Untuk menjalankan skrip yang ditulis untuk Bash: terapkan perbaikan untuk hook yang ditulis untuk Bash

Perilaku exit code 2 per event

Exit code 2 adalah cara hook memberi sinyal "berhenti, jangan lakukan ini." Efeknya bergantung pada event, karena beberapa event mewakili tindakan yang dapat diblokir (seperti panggilan tool yang belum terjadi) dan yang lain mewakili hal-hal yang sudah terjadi atau tidak dapat dicegah.

Untuk SessionStart, SubagentStart, dan PostModelSwitch, Claude Code menampilkan stderr exit code 2 di transkrip sebagai pemberitahuan <hook name> hook error, dengan cara yang sama seperti menampilkan error non-blocking. Claude tidak melihatnya, dan sesi atau subagent berlanjut. Untuk SubagentStart, pemberitahuan muncul di transkrip subagent itu sendiri, bukan di percakapan induk.

Penanganan respons HTTP

Hook HTTP menggunakan kode status HTTP dan body respons alih-alih exit code dan stdout. Untuk memblokir tindakan ketika permintaan gagal atau mengembalikan status non-2xx, atur onFailure: "block". Untuk memblokir panggilan tool atau menolak izin, kembalikan respons 2xx dengan body JSON yang berisi field keputusan yang sesuai.

Setelah error non-blocking, tindakan dilanjutkan kecuali hook tersebut adalah hook yang kegagalannya memblokir tindakan. Kecuali pada event dengan kontrak kegagalannya sendiri dalam tabel per event, seperti WorktreeCreate, Anda mendapatkan hasil berikut untuk setiap respons atau kegagalan:

• 2xx dengan body kosong: berhasil, setara dengan exit code 0 tanpa output
• 2xx dengan body objek JSON: di-parse menggunakan skema output JSON yang sama seperti hook perintah. Body yang gagal validasi skema adalah error non-blocking
• 2xx dengan body lain, seperti teks biasa: error non-blocking, ditangani sama seperti status non-2xx. Claude Code tidak menambahkan teks tersebut ke konteks Claude
• Status non-2xx: error non-blocking
• Kegagalan koneksi: error non-blocking
• Timeout: hook dibatalkan, seperti dijelaskan di bagian Timeout

Output JSON

Exit code hanya memungkinkan Anda memblokir atau tetap diam, tetapi output JSON memberi Anda kontrol yang lebih terperinci. Alih-alih keluar dengan kode 2 untuk memblokir, keluar dengan 0 dan cetak objek JSON ke stdout. Claude Code membaca field tertentu dari JSON tersebut untuk mengontrol perilaku, termasuk kontrol keputusan untuk memblokir, mengizinkan, atau mengeskalasi ke pengguna.

[!NOTE]

Pilih satu pendekatan per hook: gunakan exit code saja untuk memberi sinyal, atau keluar dengan 0 dan cetak JSON untuk kontrol terstruktur. Jika Anda mencampurnya, exit 2 tetap mempertahankan efek pemblokirannya, dan Claude Code tetap membaca field JSON, dengan satu pengecualian elicitation yang dicatat di bagian Exit code 2.

Jangan cetak apa pun selain objek JSON ke stdout. Untuk hook yang tidak async, teks lain di sana, seperti baris yang dicetak profil shell Anda saat startup, mencegah Claude Code membaca objek tersebut sebagai JSON, dan JSON hook tidak berpengaruh menunjukkan cara menemukan dan membungkam teks tersebut.

String additionalContext, systemMessage, dan initialUserMessage dari hook, serta stdout biasanya, dibatasi hingga 10.000 karakter:

• Cakupan: Claude Code mengukur setiap string secara terpisah, bahkan ketika beberapa hook berjalan untuk event yang sama. Untuk output JSON, setiap field diukur secara terpisah; stdout biasa diukur secara keseluruhan.
• Melebihi batas: kecuali untuk stdout PreCompact, Claude Code menyimpan output ke file di direktori sesi. Claude Code mengganti output tersebut dengan path file serta pratinjau hingga 2.000 karakter pertama. Hasil Bash valid yang besar ditangani dengan cara yang sama, seperti dijelaskan di bagian Batas output. Tidak seperti batas atas Bash tersebut, batas ini tidak memiliki pengaturan atau environment variable untuk menaikkannya.
• Membaca file: Claude Code tidak meminta Claude untuk membaca file tersebut, jadi pastikan apa pun yang harus selalu dilihat Claude tetap berada dalam batas.

Objek JSON mendukung tiga jenis field:

• Field universal seperti continue tercantum dalam tabel di bawah. Setiap event menerimanya, tetapi beberapa event membuangnya atau mengirimkan systemMessage ke tempat selain transkrip. Bagian setiap event menyebutkannya. terminalSequence juga berfungsi pada event tersebut, dengan pengecualian yang tercantum di bagian Memancarkan notifikasi terminal.
• decision dan reason tingkat atas digunakan oleh beberapa event untuk memblokir atau memberikan umpan balik.
• hookSpecificOutput adalah objek bersarang untuk event yang memerlukan kontrol lebih kaya. Objek ini memerlukan field hookEventName yang diatur ke nama event.

Untuk menghentikan Claude sepenuhnya:

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

Untuk hook PreToolUse dan PostToolUse, penghentian berlaku bahkan ketika panggilan tool gagal atau selesai saat Claude masih melakukan streaming respons.

Memancarkan notifikasi terminal

Hook berjalan tanpa terminal pengendali, sehingga menulis escape sequence langsung ke /dev/tty akan gagal. Sebagai gantinya, kembalikan escape sequence di field terminalSequence dan Claude Code memancarkannya untuk Anda melalui jalur penulisan terminalnya sendiri. Cara ini bebas race condition, berfungsi di dalam tmux dan GNU screen, dan berfungsi di Windows yang tidak memiliki /dev/tty.

Field ini menerima string berisi satu atau lebih escape sequence yang ada di allowlist:

• OSC 0, 1, 2: judul jendela dan ikon
• OSC 9: notifikasi iTerm2, ConEmu, Windows Terminal, dan WezTerm, termasuk progres taskbar 9;4
• OSC 99: notifikasi Kitty
• OSC 777: notifikasi urxvt, Ghostty, dan Warp
• BEL tunggal

Sequence dapat diakhiri dengan BEL atau dengan ST. Apa pun di luar allowlist, termasuk sequence kursor dan warna CSI, sequence palet OSC, hyperlink OSC 8, penulisan clipboard OSC 52, dan OSC 1337, ditolak dan field diabaikan.

Claude Code menulis sequence tersebut sendiri ketika memproses output hook Anda, sehingga field ini berfungsi pada event yang membuang systemMessage dan continue, seperti Notification dan StopFailure. Field ini memiliki dua batasan:

• Claude Code menulis sequence hanya dalam sesi interaktif, dan hanya selama antarmukanya ada di layar. Dalam mode non-interaktif dengan flag -p dan di Agent SDK, Claude Code mengabaikan field ini.
• Hook perintah WorktreeCreate tidak dapat mengembalikan JSON, karena Claude Code membaca stdout-nya sebagai path worktree. Hook HTTP WorktreeCreate mengembalikan JSON dan dapat menyertakan field ini.

Contoh di bawah memicu notifikasi desktop dari hook Notification. Escape sequence dibuat dengan escape oktal printf sehingga byte kontrol tidak pernah muncul di baris perintah shell, dan jq -n --arg membuat output JSON sehingga tanda kutip, backslash, dan baris baru dalam pesan notifikasi di-escape dengan benar:

#!/bin/bash
# Notification hook: ping the desktop when Claude Code needs attention.
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Bentuk { "terminalSequence": "..." } sama dari shell atau bahasa apa pun.

Menambahkan konteks untuk Claude

Field additionalContext meneruskan string dari hook Anda ke context window Claude. Claude Code membungkus string tersebut dalam system reminder dan menyisipkannya ke dalam percakapan pada titik di mana hook dijalankan. Claude membaca reminder tersebut pada permintaan model berikutnya, tetapi reminder tidak muncul sebagai pesan chat di antarmuka.

Kembalikan additionalContext di dalam hookSpecificOutput bersama nama event:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

Di mana reminder muncul bergantung pada event:

• SessionStart dan SubagentStart: di awal percakapan, sebelum prompt pertama
• UserPromptSubmit dan UserPromptExpansion: bersama prompt yang dikirim
• PreToolUse, PostToolUse, PostToolUseFailure, dan PostToolBatch: di samping hasil tool
• Stop dan SubagentStop: di akhir giliran. Percakapan berlanjut sehingga Claude dapat menindaklanjuti umpan balik. Lihat Kontrol keputusan Stop
• PostModelSwitch: bersama permintaan berikutnya setelah pergantian. Lihat Kontrol keputusan PostModelSwitch untuk waktunya

Ketika beberapa hook mengembalikan additionalContext untuk event yang sama, Claude menerima semua nilainya.

Jika string Anda berisi tag <system-reminder> atau </system-reminder>, Claude menerima string tersebut dengan < pada tag itu diganti dengan <.

Jika suatu nilai melebihi 10.000 karakter, Claude Code menulis teks tersebut ke file di direktori sesi dan sebagai gantinya meneruskan path file kepada Claude beserta pratinjau hingga 2.000 karakter pertama. Claude dapat membaca file tersebut, tetapi Claude Code tidak memintanya untuk melakukannya.

Gunakan additionalContext untuk informasi yang perlu diketahui Claude tentang status environment Anda saat ini atau operasi yang baru saja dijalankan:

• Status environment: branch saat ini, target deployment, atau feature flag yang aktif
• Aturan proyek bersyarat: perintah pengujian mana yang berlaku untuk file yang baru saja diedit, direktori mana yang read-only di worktree ini
• Data eksternal: issue terbuka yang ditugaskan kepada Anda, hasil CI terbaru, konten yang diambil dari layanan internal

Untuk instruksi yang tidak pernah berubah, utamakan CLAUDE.md. File ini dimuat tanpa menjalankan skrip dan merupakan tempat standar untuk konvensi proyek yang statis.

Tulis teks sebagai pernyataan faktual, bukan instruksi sistem yang bersifat imperatif. Frasa seperti "The deployment target is production" atau "This repo uses bun test" dibaca sebagai informasi proyek. Teks yang dibingkai sebagai perintah sistem di luar jalur dapat memicu pertahanan prompt injection Claude, yang menyebabkan Claude menampilkan teks tersebut kepada Anda alih-alih memperlakukannya sebagai konteks.

Claude Code menyimpan teks yang disisipkan di transkrip sesi. Untuk event di tengah sesi seperti PostToolUse atau UserPromptSubmit, ketika Anda melanjutkan dengan --continue atau --resume, Claude Code memutar ulang teks yang tersimpan alih-alih menjalankan ulang hook untuk giliran sebelumnya, sehingga nilai seperti timestamp atau SHA commit menjadi usang. Hook SessionStart berjalan lagi saat dilanjutkan dengan source diatur ke "resume", atau "fork" jika Anda menambahkan --fork-session, sehingga hook tersebut dapat memperbarui konteksnya.

Kontrol keputusan

Tidak setiap event mendukung pemblokiran atau pengendalian perilaku melalui JSON. Event yang mendukungnya masing-masing menggunakan kumpulan field yang berbeda untuk menyatakan keputusan tersebut. Gunakan tabel ini sebagai referensi cepat sebelum menulis hook:

Beberapa event juga dapat menulis ulang konten alih-alih hanya mengizinkan atau memblokirnya:

• PreToolUse: updatedInput langsung di bawah hookSpecificOutput menggantikan argumen tool sebelum tool berjalan. Lihat Kontrol keputusan PreToolUse
• PermissionRequest: updatedInput di dalam objek decision. Lihat Kontrol keputusan PermissionRequest
• PostToolUse: updatedToolOutput menggantikan hasil tool. Lihat Kontrol keputusan PostToolUse
• UserPromptSubmit: tidak dapat menggantikan prompt; hanya menyisipkan additionalContext bersamanya

Untuk kasus penggunaan redaksi atau transformasi, lakukan intersepsi di PreToolUse untuk input tool keluar dan di PostToolUse untuk hasil tool masuk.

Berikut contoh setiap pola dalam praktik:

[tab] Keputusan tingkat atas

Satu-satunya nilai untuk decision adalah "block". Untuk mengizinkan tindakan dilanjutkan, hilangkan decision dari JSON Anda, atau keluar dengan 0 tanpa JSON sama sekali:

{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}

[tab] PreToolUse

Menggunakan hookSpecificOutput untuk kontrol yang lebih kaya: mengizinkan, menolak, atau mengeskalasi ke pengguna. Anda juga dapat memodifikasi input tool sebelum tool berjalan atau menyisipkan konteks tambahan untuk Claude. Lihat Kontrol keputusan PreToolUse untuk kumpulan opsi lengkap.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

[tab] PermissionRequest

Menggunakan hookSpecificOutput untuk mengizinkan atau menolak permintaan izin atas nama pengguna. Saat mengizinkan, Anda juga dapat memodifikasi input tool atau menerapkan aturan izin sehingga pengguna tidak ditanya lagi. Lihat Kontrol keputusan PermissionRequest untuk kumpulan opsi lengkap.

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

Untuk contoh lanjutan termasuk validasi perintah Bash, pemfilteran prompt, dan skrip persetujuan otomatis, lihat Apa yang dapat Anda otomatisasi dalam panduan dan implementasi referensi validator perintah Bash.

Event hook

Setiap event berkaitan dengan satu titik dalam siklus hidup Claude Code tempat hook dapat dijalankan. Bagian-bagian di bawah ini diurutkan sesuai siklus hidup tersebut: dari penyiapan sesi melalui agentic loop hingga akhir sesi. Setiap bagian menjelaskan kapan event dipicu, matcher apa yang didukungnya, input JSON yang diterimanya, dan cara mengontrol perilaku melalui output.

SessionStart

Berjalan saat Claude Code memulai sesi baru atau melanjutkan sesi yang sudah ada. Berguna untuk memuat konteks pengembangan seperti issue yang ada atau perubahan terbaru pada codebase Anda, atau untuk menyiapkan environment variable. Untuk konteks statis yang tidak memerlukan skrip, gunakan CLAUDE.md sebagai gantinya.

SessionStart berjalan di setiap sesi, jadi jaga agar hook ini tetap cepat. Hanya hook type: "command" dan type: "mcp_tool" yang didukung. Lihat kolom hook tool MCP untuk mengetahui kapan hook mcp_tool berjalan.

Nilai matcher berkaitan dengan cara sesi dimulai:

Saat Anda memulai sesi interaktif, melanjutkan percakapan saat peluncuran dengan --continue atau --resume, atau menjalankan /clear, hook SessionStart berjalan di latar belakang. Anda dapat langsung mengetik, dan percakapan yang Anda lanjutkan muncul tanpa menunggu hook. Respons pertama Claude tetap menunggu hook selesai, sehingga konteksnya sampai ke Claude.

Saat Anda berpindah percakapan dengan /resume di dalam sesi, perpindahan tersebut justru menunggu hook selesai. Jika Anda menjalankan /clear atau berpindah ke percakapan lain saat hook latar belakang masih berjalan, apa pun yang dikembalikannya tidak diterapkan ke sesi.

Penantian yang sama berlaku saat peluncuran, termasuk sesi yang dilanjutkan: prompt yang Anda kirim saat hook SessionStart masih berjalan tidak sampai ke Claude hingga hook tersebut selesai.

Selama salah satu penantian tersebut, tekan Esc untuk mengembalikan prompt ke input tanpa mengirimnya. Hook tetap berjalan.

Input SessionStart

Selain kolom input umum, hook SessionStart menerima source serta secara opsional model, agent_type, dan session_title:

Sesi yang belum Anda beri nama tetap dapat memiliki judul yang dihasilkan. Judul tersebut bukan judul kustom dan tidak muncul di session_title.

Saat source bernilai "resume" atau "fork" dan transkrip berisi setidaknya satu respons dari Claude, hook SessionStart juga menerima empat kolom di bawah ini. Hook Anda dapat menggunakannya untuk melaporkan biaya melanjutkan percakapan yang sudah lama sebelum permintaan pertama, misalnya dalam systemMessage. Kolom-kolom ini memerlukan Claude Code v2.1.251 atau lebih baru.

Contoh ini menunjukkan input untuk sesi yang dilanjutkan 90 menit setelah respons terakhirnya:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "resume",
  "model": "claude-opus-5",
  "seconds_since_last_response": 5400,
  "context_tokens": 182340,
  "prompt_cache_likely_expired": true,
  "estimated_cache_write_usd": 1.1396
}

Kontrol keputusan SessionStart

Hook SessionStart dapat menambahkan konteks untuk Claude, menyediakan pesan pengguna pertama, menetapkan judul sesi, memantau file, dan memuat ulang skill. Kembalikan kolom untuk masing-masing, selain kolom output JSON yang tersedia untuk semua hook:

Output ini menambahkan konteks dan memberi nama sesi:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
    "sessionTitle": "auth-refactor"
  }
}

Hook yang hanya menambahkan konteks dapat mencetaknya tanpa membangun JSON, karena Claude Code menambahkan stdout teks biasa dari hook SessionStart ke konteks Claude.

Jika hook SessionStart plugin Anda menyediakan initialUserMessage atau sessionTitle, instal plugin sebelum sesi dimulai. Claude Code mengabaikan kedua kolom tersebut dari plugin yang selesai diinstal setelah hook SessionStart berjalan.

Memuat ulang skill yang diinstal hook

Agar skill yang diinstal oleh hook SessionStart tersedia dalam sesi yang sama, kembalikan reloadSkills. Penemuan skill biasanya berjalan sebelum hook SessionStart selesai, sehingga tanpanya, file yang ditulis hook ke ~/.claude/skills/ atau .claude/skills/ dapat belum ada saat prompt pertama berjalan.

Contoh ini menyinkronkan repositori skill bersama dan meminta pemindaian ulang:

#!/bin/bash

git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills

echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

URL repositori tersebut adalah placeholder. Ganti dengan repositori skill Anda sendiri.

Mempertahankan environment variable

Hook SessionStart memiliki akses ke environment variable CLAUDE_ENV_FILE, yang menyediakan path file tempat Anda dapat mempertahankan environment variable untuk perintah shell yang dijalankan Claude nanti dalam sesi.

Untuk menetapkan environment variable satu per satu, tulis pernyataan export ke CLAUDE_ENV_FILE. Gunakan append (>>) untuk mempertahankan variabel yang ditetapkan oleh hook lain:

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

Untuk menangkap semua perubahan environment dari perintah penyiapan, bandingkan variabel yang diekspor sebelum dan sesudahnya:

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

Setiap perintah Bash menjalankan isi file sebagai kode shell sebelum perintah itu sendiri, sehingga baris di dalamnya dapat menggunakan apa pun yang dievaluasi Bash, seperti referensi $PATH dalam export PATH="$PATH:./node_modules/.bin".

Variabel yang dipertahankan dalam perintah PowerShell

Perintah PowerShell juga menerima variabel dari CLAUDE_ENV_FILE, di Claude Code v2.1.296 atau lebih baru, tetapi PowerShell tidak pernah menjalankan file tersebut. Sebagai gantinya, Claude Code membaca penugasan dari file itu dan menyalinnya ke environment perintah PowerShell. Hal ini hanya dilakukan jika setiap baris merupakan salah satu dari berikut ini, mencakup semua yang ditulis oleh setiap hook dalam sesi ini dan skrip apa pun yang Anda tetapkan sebagai CLAUDE_ENV_FILE sebelum peluncuran:

• Baris kosong atau komentar #
• Satu penugasan di awal baris, ditulis export NAME=value, declare -x NAME=value, atau NAME=value, dengan nilai yang akan digunakan Bash persis seperti yang ditulis, tersusun dari campuran bagian-bagian berikut: teks tanpa tanda kutip yang hanya menggunakan huruf, angka, dan karakter _ @ % + = : , . / -, teks dalam tanda kutip tunggal, dan teks dalam tanda kutip ganda yang setiap $, backtick, atau " di dalamnya di-escape dengan backslash

Jika ada baris dari jenis lain, seperti export PATH="$PATH:./node_modules/.bin" dengan $PATH yang tidak di-escape, perintah source, atau string $'...' yang dicetak oleh direnv export bash, perintah PowerShell tidak menerima satu pun variabel, dan claude --debug mencatat Session environment is not all plain assignments. Perintah Bash tetap menerima semuanya. Di Windows, perintah PowerShell juga tidak menerima variabel yang nilainya mengandung / atau \, karena Git Bash dan Windows menulis path secara berbeda. Perintah PowerShell yang berjalan dalam sandbox tidak menerima satu pun variabel.

[!NOTE]

CLAUDE_ENV_FILE tersedia untuk hook SessionStart, Setup, CwdChanged, dan FileChanged. Event hook lainnya tidak memiliki akses ke variabel ini, demikian pula hook yang berjalan di PowerShell, baik melalui "shell": "powershell" maupun secara default di Windows tanpa Git Bash.

Setup

Hanya dipicu saat Anda meluncurkan Claude Code dengan --init-only, atau dengan --init atau --maintenance dalam mode non-interaktif dengan flag -p. Event ini tidak dipicu pada startup normal. Gunakan untuk instalasi dependensi satu kali atau pembersihan terjadwal yang Anda picu secara eksplisit dari CI atau skrip, terpisah dari startup sesi normal. Untuk inisialisasi per sesi, gunakan SessionStart sebagai gantinya.

Nilai matcher berkaitan dengan flag CLI yang memicu hook:

Saat Anda menjalankan claude --init-only, Claude Code menjalankan hook Setup dan hook SessionStart dengan matcher startup, lalu keluar tanpa memulai percakapan.

Saat Anda memulai atau melanjutkan percakapan dengan -p, Anda juga perlu menyediakan prompt, sebagai argumen atau di-pipe melalui stdin. Anda dapat melewati prompt saat hook SessionStart menyediakan initialUserMessage atau saat Anda melanjutkan sesi dengan panggilan tool yang ditangguhkan.

Jika berhasil, --init-only tidak mencetak apa pun ke terminal. Untuk memastikan hook telah berjalan, mulai dengan claude --debug-file <path> --init-only, ganti <path> dengan lokasi file log, lalu periksa log untuk entri hook Setup dan SessionStart.

Karena Setup tidak dipicu di setiap peluncuran, plugin yang memerlukan dependensi terinstal tidak dapat hanya mengandalkan Setup. Pola praktisnya adalah memeriksa dependensi pada penggunaan pertama dan menginstalnya jika belum ada, misalnya hook atau skill yang memeriksa ${CLAUDE_PLUGIN_DATA}/node_modules dan menjalankan npm install jika tidak ada. Lihat direktori data persisten untuk tempat menyimpan dependensi yang diinstal. Jika Anda mendistribusikan plugin melalui marketplace, Anda mungkin tidak memerlukan pola ini: Claude Code menginstal dependensi paket Node.js yang memenuhi syarat secara otomatis saat melakukan cache plugin.

Input Setup

Selain kolom input umum, hook Setup menerima kolom trigger yang bernilai "init" atau "maintenance":

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

Kontrol keputusan Setup

Hook Setup tidak dapat memblokir; eksekusi berlanjut pada exit code apa pun. Pada setiap exit code, Claude Code membuang kolom output JSON dari hook Setup, seperti systemMessage, continue, dan hookSpecificOutput.additionalContext. Dengan -p, stdout, stderr, dan exit code hook Setup muncul dalam output eksekusi hanya sebagai event hook_response saat Anda meluncurkan dengan --output-format stream-json --verbose.

Hook Setup memiliki akses ke CLAUDE_ENV_FILE. Jika hook Anda menulis variabel ke file tersebut, variabel itu bertahan ke perintah Bash berikutnya dalam sesi, seperti pada hook SessionStart. Hanya hook type: "command" yang berjalan pada Setup. Hook type: "mcp_tool" pada Setup selalu dilewati, seperti yang dijelaskan di Field hook tool MCP.

InstructionsLoaded

Dipicu saat file CLAUDE.md atau .claude/rules/*.md dimuat ke dalam konteks. Event ini dipicu di awal sesi untuk file yang dimuat secara langsung dan dipicu lagi nanti saat file dimuat secara lazy, misalnya saat Claude mengakses subdirektori yang berisi CLAUDE.md bersarang atau saat aturan kondisional dengan frontmatter paths: cocok. Hook ini tidak mendukung pemblokiran atau kontrol keputusan. Hook ini berjalan secara asinkron untuk tujuan observabilitas.

Event ini tidak dipicu saat Claude membaca AGENTS.md secara langsung melalui pengaturan Project instructions. Event ini dipicu saat CLAUDE.md mengimpor AGENTS.md Anda, dengan load_reason bernilai include seperti file impor lainnya, dan saat CLAUDE.md merupakan symlink ke file tersebut, sebagai pemuatan CLAUDE.md biasa.

Matcher dijalankan terhadap load_reason. Misalnya, gunakan "matcher": "session_start" agar hanya dipicu untuk file yang dimuat di awal sesi, atau "matcher": "path_glob_match|nested_traversal" agar hanya dipicu untuk pemuatan lazy.

Input InstructionsLoaded

Selain kolom input umum, hook InstructionsLoaded menerima kolom-kolom berikut:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/Users/my-project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

Kontrol keputusan InstructionsLoaded

Hook InstructionsLoaded tidak memiliki kontrol keputusan. Hook ini tidak dapat memblokir atau mengubah pemuatan instruksi. Claude Code membuang kolom output JSON miliknya, seperti systemMessage dan continue. Gunakan event ini untuk audit logging, pelacakan kepatuhan, atau observabilitas.

UserPromptSubmit

Berjalan saat prompt dikirim, sebelum Claude memprosesnya. Ini memungkinkan Anda menambahkan konteks tambahan berdasarkan prompt/percakapan, memvalidasi prompt, atau memblokir jenis prompt tertentu.

Hook UserPromptSubmit tidak hanya dipicu pada prompt yang Anda ketik. Claude Code juga menjalankannya pada:

• Tugas terjadwal bercakupan sesi yang dipicu, termasuk iterasi /loop
• Subagent latar belakang yang melapor kembali ke sesi yang memulainya
• Pesan yang dikirim sesi lain ke percakapan utama Anda

Hook UserPromptSubmit memiliki timeout default 30 detik untuk tipe command, http, dan mcp_tool, lebih singkat daripada default 600 detik untuk tipe-tipe tersebut pada sebagian besar event lainnya. Karena hook ini berjalan sebelum setiap prompt dan memblokir pemrosesan model hingga selesai, hook yang macet akan menghentikan sesi. Jika hook Anda memerlukan lebih banyak waktu, tetapkan kolom timeout dalam entri hook.

Selain hook perintah yang Anda jalankan dengan async: true, hook perintah, HTTP, atau tool MCP UserPromptSubmit yang mencapai timeout-nya akan dibatalkan dan output-nya, termasuk additionalContext apa pun, dibuang. Prompt tetap sampai ke Claude tanpa konteks tersebut. Untuk memblokir prompt sebagai gantinya, tetapkan onFailure: "block" pada hook perintah atau HTTP. Transkrip menampilkan pemberitahuan yang menyebutkan hook, timeout yang terpicu, dan bahwa output telah dibuang.

Hook callback Agent SDK pada UserPromptSubmit yang mencapai timeout-nya memblokir prompt dengan pesan yang menyebutkan nama hook dan timeout-nya, karena callback di sana dapat berfungsi sebagai gerbang kebijakan yang tidak boleh gagal secara terbuka. Sesi tetap berlanjut.

Esc selama pemeriksaan prompt

Jika Anda menekan Esc atau menginterupsi sesi saat hook masih memeriksa prompt, pemeriksaan berhenti dan prompt tidak sampai ke Claude. Teks yang Anda ketik di terminal kembali ke input prompt, dan hook memeriksanya lagi saat Anda mengirimnya ulang.

Hook dapat memblokir prompt pada saat yang sama dengan Anda menginterupsi. Prompt kemudian tetap terblokir: Anda melihat pesan blokir dari hook tersebut, dan teks tidak kembali ke input.

Input UserPromptSubmit

Selain kolom input umum, hook UserPromptSubmit menerima kolom prompt yang berisi teks yang dikirim. Konten tempelan yang diringkas menjadi placeholder [Pasted text #N] tiba dalam keadaan sudah diperluas di tempatnya. Dalam sesi tempat Claude Code menandai teks tempelan untuk Claude, konten yang diperluas tersebut berada di antara baris <pasted_content id="…"> dan baris </pasted_content id="…">, jadi perhitungkan baris-baris tersebut jika hook Anda mengurai prompt.

Hook UserPromptSubmit juga menerima session_title saat sesi memiliki judul kustom, dengan makna yang sama seperti kolom session_title SessionStart.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

Saat prompt berupa skill atau perintah kustom yang Anda ketik, seperti /deploy staging, hook menerima baris tersebut sebagaimana Anda mengetiknya, bukan konten skill yang diperluas. Jika hook memblokir prompt, perintah tidak dijalankan, sehingga perintah shell yang disisipkan skill dengan !`<command>` juga tidak dijalankan. Untuk mencocokkan nama atau argumen perintah sebagai gantinya, gunakan UserPromptExpansion.

Kontrol keputusan UserPromptSubmit

Hook UserPromptSubmit dapat mengontrol apakah prompt yang dikirim diproses dan dapat menambahkan konteks. Semua kolom output JSON tersedia.

Ada dua cara untuk menambahkan konteks ke percakapan pada exit code 0:

• Stdout teks biasa: Claude Code menambahkan stdout yang diperlakukannya sebagai teks biasa ke konteks Claude
• JSON dengan additionalContext: gunakan format JSON di bawah ini untuk kontrol yang lebih besar. Kolom additionalContext ditambahkan sebagai konteks

Tidak satu pun dari kedua saluran ini menghasilkan entri transkrip yang terlihat. Stdout biasa dan nilai additionalContext masing-masing disisipkan sebagai system reminder yang diawali dengan nama hook; Claude membaca keduanya. Untuk memastikan pengiriman, periksa debug log.

Untuk memblokir prompt, kembalikan objek JSON dengan decision bernilai "block":

Hook yang memblokir dengan keluar menggunakan kode 2 diarahkan dengan cara yang sama seperti reason: pesan pemblokiran menampilkan teks stderr kepada pengguna, dan teks tersebut tidak ditambahkan ke konteks.

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title",
    "suppressOriginalPrompt": true
  }
}

Jejak yang ditinggalkan prompt yang diblokir

Prompt yang diblokir tidak pernah sampai ke Claude, tetapi teksnya tidak dihapus dari semua tempat. Secara default, pesan pemblokiran yang ditampilkan kepada pengguna diakhiri dengan Original prompt: diikuti teks yang dikirim, dan Claude Code menulis pesan tersebut ke file transkrip sesi di disk. Untuk menghilangkan teks dari pesan, cetak JSON dengan "suppressOriginalPrompt": true di dalam hookSpecificOutput. Ini berfungsi baik saat hook memblokir dengan decision: "block" maupun dengan keluar menggunakan kode 2.

suppressOriginalPrompt hanya mengubah pesan pemblokiran. Teks yang dikirim tetap dapat muncul di file lokal seperti transkrip sesi dan riwayat prompt Anda, sehingga hook pemblokiran bukanlah cara untuk menjaga rahasia agar tidak tersimpan di disk. Untuk membatasi atau menghapus file-file tersebut, lihat Penyimpanan plaintext dan Menghapus data lokal.

UserPromptExpansion

Berjalan saat perintah yang diketik pengguna diperluas menjadi prompt sebelum sampai ke Claude. Gunakan ini untuk memblokir perintah tertentu agar tidak dipanggil secara langsung, menyisipkan konteks untuk skill tertentu, atau mencatat perintah mana yang dipanggil pengguna. Misalnya, hook yang cocok dengan deploy dapat memblokir /deploy kecuali ada file persetujuan, atau hook yang cocok dengan skill review dapat menambahkan daftar periksa review tim sebagai additionalContext.

Event ini mencakup jalur yang tidak dicakup PreToolUse: hook PreToolUse yang cocok dengan tool Skill hanya dipicu saat Claude memanggil tool tersebut, tetapi mengetik /skillname secara langsung melewati PreToolUse. UserPromptExpansion dipicu pada jalur langsung tersebut.

Dicocokkan pada command_name. Biarkan matcher kosong agar dipicu pada setiap perintah bertipe prompt.

Input UserPromptExpansion

Selain kolom input umum, hook UserPromptExpansion menerima expansion_type, command_name, command_args, command_source, dan string prompt asli. Kolom expansion_type bernilai slash_command untuk skill dan perintah kustom, atau mcp_prompt untuk prompt server MCP.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../00893aaf.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

Kontrol keputusan UserPromptExpansion

Hook UserPromptExpansion dapat memblokir perluasan atau menambahkan konteks. Semua kolom output JSON tersedia.

Hook yang memblokir dengan keluar menggunakan kode 2 diarahkan dengan cara yang sama seperti reason: pesan pemblokiran menampilkan teks stderr kepada pengguna.

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

MessageDisplay

Berjalan saat pesan asisten di-stream ke layar. Claude Code menampilkan pesan secara bertahap: setiap kali sekelompok baris yang baru selesai siap dirender, hook berjalan sekali dengan baris-baris tersebut dan Claude Code merender teks pengganti dari hook di tempatnya. Pesan yang panjang menghasilkan beberapa panggilan; pesan yang pendek mungkin hanya menghasilkan satu.

Gunakan MessageDisplay untuk:

• menghapus markdown untuk tampilan minimal
• mengubah teks yang ditampilkan aplikasi Agent SDK kepada penggunanya
• menyamarkan kunci API atau hostname internal dari respons Claude

Claude Code menahan setiap kelompok hingga hook Anda kembali, jadi jaga agar hook tetap cepat. Jika hook gagal atau mengalami timeout, Claude Code menampilkan teks asli. Timeout default untuk event ini adalah 10 detik; jika hook Anda memerlukan lebih banyak waktu, tetapkan kolom timeout dalam entri hook.

MessageDisplay hanya untuk tampilan: teks pengganti hanya mengubah apa yang dirender di layar. Transkrip dan apa yang dilihat Claude tetap menggunakan teks asli, sehingga Claude tidak pernah melihat teks pengganti, dan mode verbose menampilkan teks asli. Hook hanya menerima teks pesan asisten, sehingga hasil tool dan teks yang Anda ketik dirender tanpa perubahan.

MessageDisplay tidak mendukung matcher dan dipicu untuk setiap pesan asisten yang men-stream teks; pesan tanpa teks, seperti respons yang hanya berisi panggilan tool, tidak memicunya.

Dalam eksekusi non-interaktif, termasuk kueri Agent SDK dan claude -p, MessageDisplay berjalan sekali per pesan asisten alih-alih sekali per kelompok baris. Panggilan tunggal tersebut tiba setelah pesan selesai dan membawa teks pesan lengkap: index bernilai 0, final bernilai true, dan delta berisi seluruh pesan. Hook yang mengumpulkan teks delta untuk setiap pesan menerima total teks yang sama di kedua mode.

Input MessageDisplay

Selain kolom input umum, hook MessageDisplay menerima pengidentifikasi untuk giliran dan pesan, posisi panggilan ini di dalam pesan, dan teks baru dalam delta. Batas kelompok bergantung pada cara teks di-stream, jadi gunakan index dan final untuk melacak kemajuan melalui pesan alih-alih mengharapkan baris dikelompokkan dengan cara tertentu.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "MessageDisplay",
  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
  "index": 0,
  "final": false,
  "delta": "Here is the plan:\n"
}

Output MessageDisplay

Selain kolom output JSON yang tersedia untuk semua hook, hook MessageDisplay dapat mengembalikan displayContent untuk menggantikan delta di layar:

Hook MessageDisplay tidak memiliki kontrol keputusan. Hook ini tidak dapat memblokir pesan atau mengubah apa yang disimpan dalam transkrip atau dikirim ke Claude. Claude Code menindaklanjuti displayContent dari output JSON-nya dan membuang systemMessage serta continue.

Contoh ini menghapus format markdown dari respons Claude untuk tampilan teks biasa. Skrip membaca setiap kelompok dari stdin, menghapus penanda tebal dan backtick kode inline dari delta, lalu mengembalikan hasilnya sebagai displayContent.

[tab] macOS/Linux

Daftarkan hook perintah untuk event ini di file pengaturan Anda:

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Simpan skrip ini ke .claude/hooks/plain-display.sh di proyek Anda dan jadikan dapat dieksekusi dengan chmod +x:

#!/bin/bash
jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

[tab] Windows (PowerShell)

Daftarkan hook perintah yang menjalankan skrip melalui PowerShell:

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
            ]
          }
        ]
      }
    ]
  }
}

Flag -NoProfile melewati pemuatan profil PowerShell Anda sehingga hook dimulai dengan cepat, dan -ExecutionPolicy Bypass memungkinkan PowerShell menjalankan file skrip lokal.

Simpan skrip ini ke .claude/hooks/plain-display.ps1 di proyek Anda:

$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
$text = $batch.delta -replace '\*\*', '' -replace '`', ''
@{
  hookSpecificOutput = @{
    hookEventName = "MessageDisplay"
    displayContent = $text
  }
} | ConvertTo-Json

Kelompok tanpa markdown diteruskan tanpa perubahan. Jika skrip gagal, misalnya karena jq tidak ada, Claude Code menampilkan teks asli dan mencatat kegagalan tersebut hanya di output debug, bukan di dalam sesi.

PreToolUse

Berjalan setelah Claude membuat parameter tool dan sebelum memproses panggilan tool. Cocok dengan nama tool apa pun kecuali EndConversation: tool bawaan seperti Bash, PowerShell, Edit, Write, Read, Glob, Grep, Agent, Workflow, WebFetch, WebSearch, AskUserQuestion, dan ExitPlanMode, serta nama tool MCP apa pun.

Untuk menjalankan hook saat file tertentu berubah di disk, apa pun yang menulisnya, gunakan FileChanged alih-alih mencocokkan tool pengeditan file berdasarkan nama. Tidak seperti PreToolUse, Claude Code menjalankan hook FileChanged setelah perubahan terjadi, dan hook tersebut tidak memiliki kontrol keputusan, sehingga tidak dapat memblokir penulisan.

[!WARNING]

PreToolUse hanya berjalan saat Claude memanggil tool. Secara default, file yang Anda rujuk dengan @ di prompt Anda ditambahkan tanpa panggilan tool apa pun. Claude Code menyisipkan isinya saat membangun prompt, sehingga tidak ada hook PreToolUse yang dipicu untuk file tersebut, termasuk hook yang cocok dengan Read. PreToolUse juga tidak dipicu untuk EndConversation.

Anda dapat memblokir path tertentu dari referensi @, atau mematikan penyisipan:

• Memblokir path tertentu: tambahkan aturan deny Read untuk path tersebut
• Mematikan penyisipan: tetapkan CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 di shell, pengaturan pengguna, atau pengaturan terkelola Anda. Claude kemudian mendapatkan path yang disebutkan beserta catatan untuk membacanya menggunakan tool file-nya. Jika Claude melakukannya, hook PreToolUse Anda yang cocok akan berjalan. Variabel ini memerlukan Claude Code v2.1.299 atau lebih baru, dan Claude Code mengabaikannya di pengaturan proyek dan lokal.

Gunakan kontrol keputusan PreToolUse untuk mengizinkan, menolak, meminta konfirmasi, atau menangguhkan panggilan tool.

Hook callback Agent SDK pada PreToolUse yang melampaui timeout-nya akan memblokir panggilan tool.

Input PreToolUse

Selain kolom input umum, hook PreToolUse menerima tool_name, tool_input, dan tool_use_id.

Untuk tool MCP, input juga membawa mcp_server, sebuah objek dengan name server dan source yang menyatakan asal definisi server tersebut. Nilai source mencakup plugin, sdk, dan cakupan konfigurasi seperti user dan project. McpServerProvenance dalam referensi Agent SDK mencantumkan semuanya dan menjelaskan cara memperlakukan nilai yang tidak Anda kenali. Dasarkan keputusan kepercayaan pada source, bukan pada name atau prefiks nama tool mcp__<server>__. Kolom mcp_server memerlukan Claude Code v2.1.274 atau lebih baru.

Untuk tool file Write, Edit, dan Read, tool_input.file_path selalu absolut:

• Claude Code memperluas ~ dan path relatif sebelum hook berjalan, sehingga hook yang mencocokkan path tidak dapat dilewati melalui ~ atau penulisan relatif dari path yang sama
• Di Windows, path tiba dengan pemisah backslash, bahkan saat hook Anda berjalan di Git Bash tempat $PWD terlihat seperti /c/project
• Perbandingan yang ditulis dengan garis miring, seperti pemeriksaan /src/, tidak pernah cocok dengan path backslash, dan panggilan tool berlanjut seolah-olah hook tidak menemukan apa pun untuk diblokir
• Normalisasikan pemisah sebelum membandingkan: FILE_PATH="${FILE_PATH//\\//}" di Bash, atau file_path.replace("\\", "/") di Python, lalu cocokkan segmen path seperti /src/ alih-alih menambatkan dengan ^, karena path-nya absolut

Panggilan Write di Windows mengirimkan:

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "C:\\project\\src\\index.ts",
    "content": "..."
  },
  ...
}

Kolom tool_input bergantung pada tool:

Bash

Menjalankan perintah shell.

Saat perintah Bash mengubah file di repositori Git, Claude Code dapat mencatat apa yang berubah. Claude Code mencatat perubahan di setiap mode izin saat pengaturan bashEditDiffEnabled mengaktifkan pencatatan; entri pengaturan tersebut menjelaskan file mana yang dapat menetapkannya. Jika tidak, Claude Code hanya mencatatnya di auto mode dan mode bypassPermissions, dan hanya saat Claude Code mengarahkan Claude untuk mengedit file melalui Bash. Tetapkan bashEditDiffEnabled ke false untuk mematikan pencatatan. Perintah latar belakang dan perintah read-only tidak membawa diff.

Hook PostToolUse Anda kemudian menerima file yang berubah dalam tool_response.bashEditDiff. Daftar tersebut mencakup apa yang berubah di dalam repositori selama perintah berjalan. File yang diabaikan Git dan file di submodule tidak dicantumkan. Memerlukan Claude Code v2.1.269 atau lebih baru.

[!NOTE]

Daftar ini bersifat upaya terbaik dan dalam beta publik. Claude Code dapat melewatkan perubahan, menyertakan file yang diubah oleh proses lain pada saat yang sama, atau berhenti pada batas ukurannya. Bentuk kolom dapat berubah. Gunakan daftar ini untuk menemukan apa yang perlu ditinjau, bukan untuk menegakkan kebijakan.

changedFiles dan files mencantumkan apa yang diubah oleh perintah; kolom lainnya menyatakan seberapa lengkap dan seberapa andal daftar tersebut.

PowerShell

Menjalankan perintah PowerShell. Lihat tool PowerShell untuk ketersediaan berdasarkan platform.

Kolomnya sama dengan tool Bash, dengan string perintah di command:

Cocokkan Bash|PowerShell di hook yang memeriksa perintah shell, agar mencakup kedua tool:

• Di Windows, di mana pun tool PowerShell diaktifkan, Claude memperlakukan PowerShell sebagai shell utama dan mengarahkan perintah shell melaluinya.
• Di Windows tanpa Git Bash, tool tersebut diaktifkan secara otomatis dan Claude Code sama sekali tidak mendaftarkan tool Bash.
• Hook yang hanya cocok dengan Bash tidak pernah dipicu di sana.

Write

Membuat atau menimpa file.

Edit

Mengganti string di file yang sudah ada.

Read

Membaca isi file.

Glob

Menemukan file yang cocok dengan pola glob.

Grep

Mencari isi file dengan ekspresi reguler.

WebFetch

Mengambil dan memproses konten web.

WebSearch

Mencari di web.

Agent

Memunculkan subagent.

Saat panggilan Agent latar depan selesai, hook PostToolUse Anda menerima hasil subagent dan telemetri eksekusi dalam tool_response. Baca kolom-kolom ini untuk memeriksa eksekusi; untuk rekapitulasi token dan biaya di seluruh subagent, gunakan penghitung token dan biaya yang difilter ke query_source "subagent", karena totalTokens dan usage hanya mencakup permintaan terakhir:

Di Claude Code v2.1.271 atau lebih baru, subagent yang berjalan dengan tool SubagentHandback, yang disediakan Claude Code di auto mode, menyampaikan laporannya melalui tool tersebut alih-alih mengembalikannya sebagai teks. Kolom content dari hasil completed-nya kemudian membawa catatan singkat tentang penyerahan tersebut, bukan laporannya sendiri. Untuk membaca laporan, cocokkan hook PreToolUse atau PostToolUse pada SubagentHandback dan baca tool_input.message.

Untuk subagent latar belakang, tool kembali saat tugas berpindah ke latar belakang, sehingga tool_response tidak membawa kolom penggunaan: peluncuran latar belakang langsung kembali, dan tugas latar depan yang dipindahkan Claude Code ke latar belakang di tengah eksekusi kembali pada transisi tersebut. Respons tersebut memiliki status: "async_launched", agentId, description, prompt, outputFile, dan resolvedModel.

Pada respons completed, resolvedModel menyebutkan model yang digunakan subagent saat dimulai, yang dapat berbeda dari nilai model di tool_input, misalnya ketika availableModels atau override lain berlaku. Pada respons async_launched, resolvedModel menyebutkan model yang digunakan ketika agent berpindah ke latar belakang, sehingga pertukaran yang terjadi sebelum dipindahkan ke latar belakang tercermin di sana.

AskUserQuestion

Mengajukan satu hingga empat pertanyaan pilihan ganda kepada pengguna.

ExitPlanMode

Menampilkan rencana dan meminta pengguna untuk menyetujuinya sebelum Claude meninggalkan plan mode. Claude menulis rencana ke file di disk sebelum memanggil tool, sehingga tool_input literal dari model biasanya kosong. Claude Code menyisipkan isi rencana dan path file sebelum meneruskan input ke hook.

Di PostToolUse, tool_response adalah objek dengan kolom plan dan filePath yang berisi rencana yang disetujui, ditambah flag status internal. Baca tool_response.plan untuk isi rencana alih-alih membaca ulang file dari disk.

Kontrol keputusan PreToolUse

Hook PreToolUse dapat mengontrol apakah panggilan tool berlanjut. Tidak seperti hook lain yang menggunakan field decision tingkat atas, PreToolUse mengembalikan keputusannya di dalam objek hookSpecificOutput. Ini memberinya kontrol yang lebih kaya: empat hasil (allow, deny, ask, atau defer) ditambah kemampuan untuk memodifikasi input tool sebelum eksekusi. Untuk mengizinkan atau menulis ulang perintah Monitor, lihat Mencocokkan perintah Monitor.

Saat beberapa hook PreToolUse mengembalikan keputusan yang berbeda, urutan prioritasnya adalah deny > defer > ask > allow.

Hook yang memblokir dengan keluar menggunakan kode 2 diarahkan dengan cara yang sama seperti "deny": Claude melihat pesan stderr sebagai alasan penolakan.

Saat hook mengembalikan "ask", permintaan izin yang ditampilkan kepada pengguna menyertakan label yang mengidentifikasi asal hook: [settings] untuk hook dari file pengaturan mana pun atau dari frontmatter agent, [plugin:<name>] untuk hook plugin, atau [skill] untuk hook dari frontmatter skill. Ini membantu pengguna memahami sumber konfigurasi mana yang meminta konfirmasi.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

[!NOTE]

PreToolUse sebelumnya menggunakan kolom decision dan reason tingkat atas, tetapi kolom tersebut sudah deprecated untuk event ini. Gunakan hookSpecificOutput.permissionDecision dan hookSpecificOutput.permissionDecisionReason sebagai gantinya. Nilai deprecated "approve" dan "block" masing-masing dipetakan ke "allow" dan "deny". Event lain seperti PostToolUse dan Stop tetap menggunakan decision dan reason tingkat atas sebagai format saat ini.

updatedInput PreToolUse dalam auto mode

Saat hook Anda mengembalikan updatedInput tanpa permissionDecision dalam auto mode, Claude Code dapat menolak panggilan yang diubah. Server meninjau input yang ditulis Claude, bukan input yang dikembalikan hook Anda. Dalam sesi terminal interaktif dan sesi VS Code pada koneksi langsung ke API Anthropic, penolakan tersebut menyertakan teks ini:

a hook changed this call's input after auto mode reviewed it

Setelah penolakan dengan teks ini, Claude dapat mengeluarkan panggilan yang diubah lagi agar server meninjaunya. Jika Claude mengulangi input yang diubah secara persis dalam respons berikutnya, hook Anda tetap berjalan:

• Hook dapat menolak panggilan atau mengirimkannya ke permintaan izin
• updatedInput apa pun yang dikembalikannya dibuang, sehingga yang dijalankan adalah apa yang ditinjau server

Anda tidak perlu mengubah hook Anda untuk penolakan ini kecuali Claude memberi tahu Anda dalam balasannya bahwa auto mode tidak dapat memeriksa panggilan tersebut.

Dalam sesi yang menampilkan teks ini, hook command di pengaturan atau file hook plugin dapat mengubah panggilan Bash, PowerShell, Monitor, Edit, Write, dan NotebookEdit tanpa penolakan ini. Penolakan tetap dapat muncul, misalnya saat hook mana pun mengubah panggilan sebelumnya dalam respons Claude yang sama atau perintah Bash meminta untuk berjalan di luar sandbox.

Keputusan ask PreToolUse di auto mode

Di auto mode, "ask" dari hook PreToolUse biasanya mengirimkan panggilan tool ke permintaan izin, dan pengklasifikasi tidak memutuskannya. Beberapa panggilan mengambil jalur yang berbeda:

• Panggilan yang juga ditandai oleh pemeriksaan Claude Code sendiri: ini termasuk penulisan ke path yang dilindungi dan perintah yang meminta untuk berjalan di luar sandbox. Pengklasifikasi dapat menolak salah satu panggilan ini sebelum permintaan apa pun muncul. Jika pengklasifikasi menyetujui, panggilan biasanya tetap diteruskan ke permintaan izin.
• Panggilan SubagentHandback: tool ini mengirimkan laporan subagent. Tidak ada permintaan izin yang muncul untuknya, dan panggilan tetap berjalan meskipun pengklasifikasi keberatan.

Untuk menghentikan panggilan SubagentHandback, kembalikan "deny". Claude Code kemudian memberi tahu subagent, hingga tiga kali, bahwa laporannya tidak terkirim dan untuk memanggil tool lagi. Jika hook Anda terus menolak, subagent berakhir tanpa mengirimkan laporan melalui tool ini, dan percakapan yang menunggunya mendapat catatan yang menyatakan hal tersebut.

Tool yang memerlukan interaksi pengguna

AskUserQuestion dan ExitPlanMode memerlukan interaksi pengguna. Dalam mode non-interaktif dengan flag -p, Claude Code hanya menawarkannya saat eksekusi memiliki host izin untuk menerima permintaan, seperti callback canUseTool Agent SDK.

Hook PreToolUse memenuhi persyaratan tersebut jika melakukan hal berikut:

1. Membaca input tool dari stdin
2. Mengumpulkan jawaban melalui UI Anda sendiri
3. Mengembalikan permissionDecision: "allow" bersama updatedInput yang berisi jawaban, sehingga tool berjalan tanpa permintaan

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. Output ini menjawab satu pertanyaan dengan React:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "questions": [
        {
          "question": "Which framework?",
          "header": "Framework",
          "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}],
          "multiSelect": false
        }
      ],
      "answers": {"Which framework?": "React"}
    }
  }
}

Tool MCP yang ditandai oleh 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.

Menangguhkan 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. Ini memungkinkan proses pemanggil tersebut menjeda Claude pada suatu panggilan tool, mengumpulkan input melalui antarmukanya sendiri, lalu melanjutkan dari titik terakhir.

Claude Code hanya mematuhi "defer" dalam mode non-interaktif dengan flag -p, dan hanya ketika Claude melakukan satu panggilan tool dalam giliran tersebut:

• Dalam sesi interaktif: Claude Code mencatat peringatan ke log dan mengabaikan hasil hook
• Beberapa panggilan tool sekaligus: "defer" diabaikan dengan peringatan dan tool berjalan melalui alur izin normal

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

1. Claude memanggil AskUserQuestion. Hook PreToolUse dipicu.
2. Hook mengembalikan permissionDecision: "defer". Tool tidak dieksekusi. Giliran berakhir dengan hasil yang membawa stop_reason: "tool_deferred", dan panggilan tool yang tertunda tetap berada di 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.

Field deferred_tool_use membawa id, name, dan input dari tool:

{
  "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", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false }] }
  }
}

Tidak ada timeout atau batas retry. Sesi tetap tersimpan di disk sampai pembersihan retensi cleanupPeriodDays menghapusnya, setelah 30 hari secara default.

Jika jawaban belum siap saat Anda melanjutkan, hook dapat mengembalikan "defer" lagi. Jika Anda mengirim prompt bersama resume tersebut, Claude menjawabnya tanpa hasil tool dan tidak menjalankan panggilan itu. Lanjutkan tanpa prompt sampai hook mengembalikan "allow" atau "deny".

[!NOTE]

Untuk melanjutkan sesi yang ditangguhkan dalam plan mode, berikan --permission-prompt-tool bersama --resume agar Claude Code dapat menampilkan rencana untuk disetujui. Untuk kondisi lainnya, lihat Melanjutkan dalam plan mode dengan -p. Memerlukan Claude Code v2.1.246 atau lebih baru.

Saat Anda melanjutkan dengan -p, Claude Code tidak memulihkan mode izin tersimpan lainnya. Claude Code memulai run dalam mode izin yang akan digunakan oleh run claude -p baru, jadi berikan --permission-mode atau --dangerously-skip-permissions lagi jika sesi yang ditunda menggunakan salah satunya.

Melanjutkan ketika tool yang ditunda tidak tersedia

Hasil dengan stop_reason: "tool_deferred_unavailable" berarti tool dari panggilan yang ditunda tidak tersedia di sesi yang dilanjutkan, misalnya karena server MCP-nya tidak terhubung. Hook PreToolUse Anda tidak dijalankan, dan field deferred_tool_use pada hasil menyebutkan nama tool tersebut.

Selama panggilan masih tertunda, prompt apa pun yang Anda kirim tidak sampai ke Claude dan run keluar dengan kode 1. Field result diawali dengan <tool> isn't available, so its deferred call didn't run. Jalankan panggilan tersebut, atau buang agar tidak dijalankan:

• Untuk menjalankan panggilan: buat tool tersedia dan lanjutkan lagi.
• Untuk membuang panggilan: lanjutkan dengan prompt dan CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL diatur ke 1. Claude menerima error sebagai hasil panggilan dan menjawab prompt Anda. Saat Anda melanjutkan nanti, tidak ada panggilan yang tertunda.

Saat Anda membuang panggilan, run menulis hasil tool_deferred_unavailable dengan field result kosong, lalu jawaban Claude dalam hasil kedua. Run keluar dengan kode 0 kecuali jawaban tersebut berupa error. Jika Anda mengatur variabel tersebut dan tidak mengirim prompt, run tetap membuang panggilan dan keluar dengan kode 1.

Sebelum v2.1.319, Claude Code menjawab prompt tanpa hasil tool dan membuang panggilan tersebut. Pada versi-versi tersebut, kirim prompt baru setelah tool tersedia.

PermissionRequest

Berjalan saat Claude Code akan meminta izin Anda untuk menggunakan tool. Dalam sesi yang tidak dapat menampilkan permintaan, 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. Untuk panggilan yang mencapai --permission-prompt-tool atau callback canUseTool Agent SDK, hook berjalan bersamaan dengan host Anda, dan mana pun yang memutuskan lebih dulu yang berlaku. Gunakan kontrol keputusan PermissionRequest untuk mengizinkan atau menolak atas nama pengguna.

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

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

Dicocokkan pada nama tool, dengan nilai yang sama seperti PreToolUse.

Input PermissionRequest

Hook PermissionRequest menerima field 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 ketika allowManagedPermissionRulesOnly menyembunyikan opsi penyimpanan aturan. Dialog tersebut juga dapat menawarkan opsi yang tidak memiliki entri saran, seperti Yes, and switch to auto mode, yang mengubah mode izin secara langsung, bukan melalui pembaruan izin.

Hook PreToolUse berjalan sebelum setiap panggilan tool, baik panggilan tersebut memerlukan izin maupun tidak. Hook PermissionRequest hanya berjalan ketika Claude Code akan meminta izin kepada Anda, atau ketika Claude Code akan menolak secara otomatis panggilan yang tidak dapat menampilkan permintaan izin. Kedua event ini 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 field output JSON yang tersedia untuk semua hook, skrip hook Anda dapat mengembalikan objek decision dengan field khusus event berikut:

Untuk mengizinkan atau menulis ulang perintah Monitor, lihat Mencocokkan perintah Monitor.

Hook yang keluar dengan kode 2 tanpa objek decision membiarkan alur izin tidak berubah, dan stderr-nya dibuang. Untuk memberikan atau menolak permintaan, kembalikan objek decision.

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

Entri pembaruan izin

Field output updatedPermissions dan field input permission_suggestions sama-sama menggunakan array objek entri yang sama. Setiap entri memiliki type yang menentukan field lainnya, dan destination yang mengontrol ke mana perubahan ditulis.

[!NOTE]

setMode dengan bypassPermissions hanya berlaku jika Anda meluncurkan sesi dengan mode bypass yang sudah tersedia: --dangerously-skip-permissions, --permission-mode bypassPermissions, --allow-dangerously-skip-permissions, atau permissions.defaultMode: "bypassPermissions" di pengaturan pengguna, --settings, atau pengaturan terkelola. Jika tidak, pembaruan tersebut tidak berpengaruh. Pembaruan juga tidak berpengaruh ketika permissions.disableBypassPermissionsMode menonaktifkan mode tersebut, atau ketika sesi dimulai dalam restricted mode.

bypassPermissions tidak pernah disimpan sebagai defaultMode terlepas dari destination.

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

Hook dapat mengembalikan salah satu permission_suggestions yang diterimanya sebagai output updatedPermissions-nya sendiri.

PostToolUse

Berjalan segera setelah tool berhasil diselesaikan.

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

Cocokkan secara 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 menemukan sendiri apa yang berubah, misalnya dengan menjalankan git status --porcelain, yang juga mencantumkan file yang tidak terlacak 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.

PostToolUse setelah interupsi

Jika hook PostToolUse berhenti lebih awal setelah Anda mengirim pesan atau menginterupsi selama panggilan tool, periksa apakah Anda menekan Ctrl+Enter, Enter, atau Esc:

• Ctrl+Enter: jika menekannya mengakhiri giliran saat tool sedang berjalan dan tool selesai, hook PostToolUse Anda berjalan pada hasilnya dan memiliki waktu 10 detik untuk selesai. Tombol ini berfungsi sebagai Esc jika Anda mengantrekan perintah ! sebelum pesan Anda atau tugas latar belakang dinonaktifkan, misalnya dengan CLAUDE_CODE_DISABLE_BACKGROUND_TASKS.
• Enter: pesan yang Anda antrekan dengan Enter tidak menginterupsi giliran, sehingga hook mempertahankan timeout biasanya.
• Esc: Anda langsung membatalkan hook, jadi kirim pesan dengan Enter atau Ctrl+Enter ketika hook harus berjalan.

Ketika 10 detik habis, Claude Code menghentikan paksa command hook yang masih berjalan, berapa pun timeout-nya. Agar command hook yang lebih lama dapat selesai, jalankan dengan async: true, yang berarti hook tidak dapat memblokir atau menulis ulang hasilnya.

Sebelum v2.1.319, hook tidak dimulai setelah Anda menginterupsi giliran dengan pesan, dan hook yang sedang berjalan dihentikan.

Input PostToolUse

Hook PostToolUse dipicu setelah 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 tiba dalam format yang sama seperti untuk PreToolUse: selalu absolut, dengan separator native platform, jadi 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 menggantikan 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
    }
  }
}

[!WARNING]

updatedToolOutput hanya mengubah apa yang dilihat Claude. Tool sudah berjalan pada saat hook dipicu, sehingga file apa pun yang ditulis, perintah yang dieksekusi, atau permintaan jaringan yang dikirim sudah berlaku. Telemetri seperti span tool OpenTelemetry dan event analitik juga menangkap output asli sebelum hook berjalan. Untuk mencegah atau memodifikasi panggilan tool sebelum berjalan, gunakan hook PreToolUse sebagai gantinya.

Nilai pengganti harus sesuai dengan bentuk output tool. Tool bawaan mengembalikan objek terstruktur, bukan string biasa. Misalnya, Bash mengembalikan objek dengan field stdout, stderr, interrupted, dan isImage. Untuk tool bawaan, nilai yang tidak sesuai dengan skema output tool akan diabaikan dan output asli yang digunakan. Output tool MCP diteruskan tanpa validasi skema. Menghapus detail error yang dibutuhkan Claude dapat menyebabkannya melanjutkan berdasarkan asumsi yang salah.

Menganotasi 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 memberi tahunya sesuatu tentang apa yang dikembalikan oleh panggilan sebelum pengklasifikasi meninjau tindakan selanjutnya. Field ini memerlukan Claude Code v2.1.236 atau lebih baru.

Contoh di bawah ini memberi tahu pengklasifikasi dari mana output kueri 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 sebagai konteks yang tidak terverifikasi dan disediakan oleh aplikasi. Catatan tidak pernah menetapkan niat pengguna, dan jika catatan mengklaim bahwa Anda menyetujui atau meminta sesuatu, pengklasifikasi memeriksa klaim tersebut terhadap pesan Anda sendiri dalam percakapan
• Callback Agent SDK in-process: 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 semacam 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 tidak terverifikasi. Ketika hook dari kedua kelompok menganotasi panggilan yang sama, pengklasifikasi memperlakukan catatan gabungan sebagai tidak terverifikasi

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 pengklasifikasi: transkrip pengklasifikasi menghilangkan pencarian read-only seperti pembacaan file dan pencarian. Claude Code membuang catatan yang dilampirkan pada salah satu panggilan tersebut
• Interaksi dengan penulisan ulang: ketika catatan mendeskripsikan output yang Anda ganti dengan updatedToolOutput, kembalikan kedua field dalam respons hook yang sama. Claude Code membuang catatan jika penulisan ulang tersebut ditolak atau penulisan ulang dari hook lain menggantikannya. Claude Code mengirimkan catatan yang Anda kembalikan tanpa penulisan ulang bahkan ketika hook lain menulis ulang output

[!WARNING]

Pengklasifikasi membaca konten yang Anda tempatkan di classifierContext sebagai informasi dari aplikasi yang menghosting sesi, jadi jangan menyalin output tool yang tidak tepercaya atau teks pihak ketiga ke dalamnya. Batasi catatan pada pernyataan singkat tentang satu panggilan ini, seperti fakta tentang asalnya atau pernyataan pengguna tentangnya; jangan gunakan field ini untuk mengirimkan pesan yang tidak terkait atau aliran event.

PostToolUseFailure

Berjalan ketika tool yang 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.

[!NOTE]

Event ini tidak dipicu untuk panggilan tool yang ditolak sebelum eksekusi: nama tool yang tidak dikenal, input yang gagal dalam validasi skema atau validasi khusus tool, atau penolakan izin. Penolakan validasi dikembalikan sebagai hasil tool_use_error dan terjadi sebelum hook berjalan, sehingga tidak memicu PreToolUse maupun PostToolUseFailure. Penolakan izin memicu PreToolUse tetapi tidak memicu event ini; lihat PermissionDenied.

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 ini 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 adalah teks yang sama yang diterima Claude sebagai hasil tool yang gagal. Formatnya bervariasi menurut tool dan 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
• 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 barisnya 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 telah diselesaikan, sebelum Claude Code mengirim permintaan berikutnya ke model. PostToolUse dipicu sekali per tool, yang berarti dipicu secara bersamaan ketika Claude melakukan panggilan tool paralel. PostToolBatch dipicu tepat sekali dengan batch lengkap, sehingga menjadi tempat yang tepat untuk menyisipkan 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, yaitu array yang mendeskripsikan 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 bersangkutan. Nilainya adalah string yang diserialisasi 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.

[!NOTE]

Bentuk tool_response berbeda dari milik PostToolUse. PostToolUse meneruskan objek Output terstruktur dari tool, seperti {filePath: "...", type: "create"} untuk Write; PostToolBatch meneruskan konten tool_result terserialisasi yang dilihat model.

Kontrol keputusan PostToolBatch

Hook PostToolBatch dapat menyisipkan 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 tersebut tetap ada dalam percakapan, sehingga Claude melihatnya ketika percakapan berlanjut.

PermissionDenied

Berjalan ketika auto mode menolak panggilan tool, termasuk ketika 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 model dapat 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 ini 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 model dapat 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 model dapat 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.

Tipe quota_auto_resume_fired, quota_auto_resume_stale, dan quota_auto_resume_disabled memerlukan Claude Code v2.1.234 atau yang lebih baru. Tipe auth_storage_failure memerlukan v2.1.288 atau yang 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.

[!NOTE]

Jenis permission_prompt, idle_prompt, elicitation_dialog, dan elicitation_url_dialog berbagi pengaturan waktu dengan notifikasi desktop, sehingga dalam sesi terminal Anda hanya melihatnya ketika Anda tampak jauh dari terminal:

• Harapkan permission_prompt setelah Anda tidak mengetik selama sekitar enam detik. Timer dimulai ketika permintaan izin muncul, dan setiap penekanan tombol menundanya. Untuk menjalankan hook segera ketika Claude meminta izin untuk menggunakan tool, gunakan PermissionRequest sebagai gantinya.
• Harapkan idle_prompt sekitar 60 detik setelah Claude selesai merespons, dan hanya jika Anda belum mengetik sejak itu dan tidak ada agent latar belakang, seperti subagent latar belakang, yang masih berjalan. Claude Code tidak mengirim idle_prompt saat menunggu batas penggunaan claude.ai di-reset. Ketika penantian berakhir dengan sendirinya, salah satu jenis quota_auto_resume_* dipicu sebagai gantinya.
• Harapkan elicitation_dialog untuk formulir elicitation, atau elicitation_url_dialog untuk permintaan URL browser, setelah Anda tidak mengetik selama sekitar enam detik. Keduanya berbagi gerbang enam detik yang sama dengan permission_prompt: timer dimulai ketika dialog muncul, dan setiap penekanan tombol menundanya.

Permintaan izin atau elicitation yang tiba saat dialog lain sedang ditampilkan di layar tetap menggunakan gerbang enam detik yang sama, dihitung sejak permintaan tiba. Notifikasinya dapat mencapai Anda saat permintaan masih menunggu di belakang dialog yang terbuka.

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

• Harapkan permission_prompt 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 tergantung pada jenis notifikasi. Konfigurasi ini memicu skrip peringatan khusus izin ketika Claude membutuhkan persetujuan izin dan notifikasi yang berbeda ketika Claude sedang 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 mereka 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 in-process 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 dikirimkan 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 ekspresi reguler, 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 menyisipkan 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 menyisipkan konteks yang dikembalikan hanya ketika konteks subagent belum memuat salinan dari eksekusi sebelumnya. Salinan yang disisipkan saat peluncuran tetap di tempatnya, sehingga prompt cache subagent tetap utuh. Setelah auto-compaction membuang salinan tersebut, Claude Code menyisipkan konteks dari eksekusi berikutnya lagi.

SubagentStop

Berjalan ketika subagent Claude Code 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 itu 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 satu dari agent tersebut selesai. Untuk event tersebut, agent_type adalah nama agent yang dijalankan oleh sesi itu sendiri, seperti yang diatur dengan --agent atau pengaturan agent, dan string kosong ketika sesi berjalan tanpanya.

matcher yang menyebutkan jenis agent tidak mencocokkan agent_type yang kosong. Hook yang matcher-nya dihilangkan, "", atau "*", atau merupakan ekspresi reguler 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 memuat teks penutup subagent, jika ada, yang bukan merupakan 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 dengan 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 dengan kode 2 mengirimkan pesan stderr-nya dengan cara yang sama. Untuk menyisipkan konteks ke sesi induk setelah subagent kembali, gunakan hook PostToolUse pada tool Agent sebagai gantinya.

TaskCreated

Berjalan ketika 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 exit code 2 atau dengan keputusan JSON. 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 terus 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 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 lulus 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, menghentikan rekan tim 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 selesai merespons. Tidak berjalan jika penghentian terjadi karena interupsi pengguna. Error API memicu StopFailure sebagai gantinya.

[!TIP]

Perintah /goal adalah pintasan bawaan untuk hook Stop berbasis prompt dengan cakupan sesi. Gunakan ini ketika Anda ingin Claude terus bekerja menuju suatu kondisi tanpa menulis konfigurasi hook.

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. Hitungan kelanjutan berturut-turut di-reset setiap kali Claude memanggil tool. 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 nyaring 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 telah selesai" dari "sesi dijeda menunggu pekerjaan latar belakang untuk membangunkannya kembali". Kedua array ada ketika registri tugas dapat dijangkau dan kosong ketika tidak ada yang sedang berjalan atau dijadwalkan.

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

Setiap entri dalam session_crons mendeskripsikan 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 dengan kode 2 dirutekan dengan cara yang sama seperti reason: Claude menerima pesan stderr sebagai penjelasan mengapa harus melanjutkan.

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

Gunakan additionalContext ketika hook bekerja sesuai rancangan dan memberikan panduan kepada Claude, seperti "jalankan test suite sebelum selesai". Ini membuat percakapan terus 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 alih-alih 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 lulus 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 memberikan 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 setiap keputusan pemblokiran 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 bertindak berdasarkan keputusan pemblokiran dari output JSON hook ConfigChange dan membuang systemMessage dan continue. Perubahan yang diblokir tidak menampilkan 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 alat seperti direnv yang mengelola lingkungan per direktori.

Hook CwdChanged memiliki akses ke CLAUDE_ENV_FILE. Jika hook Anda menulis variabel ke file tersebut, variabel 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 mengatur secara dinamis 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 mereka 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 di tab Workspace /permissions
• Anda menambahkan direktori yang sudah menjadi 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 ketika hook berjalan. Claude Code membuang field continue dari output JSON mereka dan menampilkan 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 filesystem watcher, bukan dengan memeriksa panggilan tool, sehingga hook dijalankan 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 umumnya adalah memuat ulang environment variable ketika file konfigurasi proyek berubah.

matcher untuk event ini memiliki dua peran:

• Membangun daftar pantauan: nilainya dipisahkan pada | 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 tersebut:

{
  "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. Pemeriksaan grep-nya menguji hal yang sama dengan yang dihapus oleh perl, yaitu CR di akhir baris, sehingga eksekusi setelah normalisasi keluar tanpa menyentuh file. Pemeriksaan 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 watcher hanya ketika ada sesuatu yang menyebutkan file untuk dipantau, jadi isi daftar awal 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 di 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, saat 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 memperbarui secara dinamis 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 Claude Code membuat worktree dalam kasus seperti berikut:

• Anda memulai sesi dengan claude --worktree
• Claude membuat worktree selama sesi dan beralih ke dalamnya dengan tool EnterWorktree
• Sebuah subagent menggunakan isolation: "worktree"
• Sebuah workflow menjalankan agent di worktree-nya sendiri
• Claude Code mengisolasi sesi latar belakang di worktree-nya sendiri
• claude remote-control dalam mode worktree memulai sesi di worktree-nya sendiri

Hook WorktreeCreate tidak berjalan untuk worktree yang ditambahkan Claude melalui Bash, dan hook dari plugin tidak berjalan untuk worktree yang dibuat ketika Anda meluncurkan dengan --worktree dan --tmux:

• git worktree add melalui Bash: untuk memeriksa atau memblokir perintah tersebut, tambahkan hook PreToolUse dengan matcher Bash.
• --worktree dengan --tmux: Claude Code membuat worktree sebelum memuat plugin, sehingga hook WorktreeCreate dari plugin tidak berjalan. Agar hook Anda berjalan dengan kedua flag tersebut, definisikan hook di file pengaturan sebagai gantinya. Sebelum v2.1.300, hook WorktreeCreate dari plugin juga tidak berjalan dengan --worktree saja.

Secara default, Claude Code membuat salinan kerja terisolasi dengan git worktree. Mengonfigurasi hook WorktreeCreate menggantikan perilaku git default tersebut, sehingga Anda dapat menggunakan sistem kontrol versi lain seperti SVN, Perforce, atau Mercurial.

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

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

Claude Code bertindak berdasarkan 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:

{
  "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 tersebut. echo pada baris terakhir adalah yang dibaca Claude Code sebagai path worktree. Alihkan output lain 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 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 me-resolve path relatif terhadap direktori tempat hook dijalankan, dengan meringkas 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. Error menyebutkan komponen yang ditolak. Symlink yang di-commit ke repositori dapat mengalihkan worktree ke luar repositori. Kembalikan path yang dinormalisasi dan tidak melewati symlink di dalam repositori.

WorktreeRemove

Berjalan ketika Claude Code membersihkan worktree yang dibuat oleh hook WorktreeCreate Anda. Event ini terpicu ketika:

• Anda keluar dari sesi worktree interaktif dan memilih untuk menghapus worktree ketika Claude Code meminta Anda
• Anda keluar dari sesi worktree interaktif yang belum Anda beri nama, Claude Code tidak menemukan file yang berubah atau tidak terlacak, dan Claude Code menghapus worktree tanpa meminta konfirmasi Anda
• Anda menghapus sesi latar belakang yang berjalan di worktree tersebut
• Anda meminta Claude untuk keluar dan menghapus worktree selama sesi, dan Claude menghapusnya dengan tool ExitWorktree
• Sesi yang dimulai oleh claude remote-control dalam mode worktree berakhir tanpa crash, dan Claude Code tidak menemukan file yang berubah atau tidak terlacak serta tidak ada commit baru di worktree-nya
• Anda menghentikan claude remote-control saat sesi yang dimulainya dalam mode worktree masih berjalan, dan Claude Code tidak menemukan file yang berubah atau tidak terlacak serta tidak ada commit baru di worktree-nya

Ketika subagent atau agent workflow selesai, Claude Code menyimpan worktree yang dibuat oleh hook WorktreeCreate Anda untuknya dan tidak menjalankan hook WorktreeRemove Anda. Hapus sendiri worktree tersebut ketika pekerjaan selesai.

Claude Code tidak meminta konfirmasi Anda sebelum hook Anda berjalan untuk panggilan ExitWorktree atau pembersihan claude remote-control. ExitWorktree menolak menghapus worktree yang dibuat hook kecuali panggilan tersebut menyertakan discard_changes: true, yang menjadikan hook Anda sebagai pemeriksaan terakhir pada jalur tersebut.

Claude Code menggunakan git untuk mencari file yang berubah atau tidak terlacak, sehingga tidak menemukan apa pun di worktree yang bukan checkout git atau tidak berada di dalamnya, bahkan ketika direktori tersebut berisi pekerjaan yang belum di-commit. Periksa pekerjaan tersebut di hook WorktreeRemove Anda sebelum hook menghapus apa pun.

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:

• Tanpa hook WorktreeRemove: Claude Code melakukan fallback ke git untuk penghapusan saat keluar atau melalui ExitWorktree, dan menyimpan worktree ketika claude remote-control melakukan pembersihan:
  • Anda keluar dari sesi worktree, atau Claude memanggil ExitWorktree: Claude Code menghapus path yang dikembalikan oleh hook WorktreeCreate Anda seperti yang dilakukan git worktree remove --force, 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.
  • claude remote-control membersihkan worktree sesi: worktree tetap ada di disk, dan terminal yang menjalankan claude remote-control menampilkan worktree removal failed, kept: <path>.
  • Anda menghapus sesi latar belakang: lihat Apa yang dihapus saat menghapus sesi.
• 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 menghapus. 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 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. Pada jalur tersebut, 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.

Claude Code meneruskan path yang dikembalikan oleh WorktreeCreate sebagai worktree_path dalam 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 dikirim 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 awal stderr-nya, dan menyatakan apakah menghapus sesi lagi tetap akan menghapus direktori tersebut.
• Jika claude remote-control sedang membersihkan worktree sesi, terminal yang menjalankannya menampilkan worktree removal failed, kept: <path>.

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 terpicu. Jika compaction dipicu secara proaktif sebelum batas konteks, Claude Code melewatinya dan percakapan berlanjut tanpa di-compact. 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 ketika mereka 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
}

Output PreCompact

Ketika hook PreCompact keluar dengan 0 dan tidak memblokir, Claude Code menggunakan stdout-nya sebagai instruksi untuk ringkasan compaction. Jaga stdout tersebut di bawah 10.000 karakter per hook. Claude Code memotong output yang lebih panjang pada batas tersebut dan menambahkan penanda.

PostCompact

Berjalan setelah Claude Code menyelesaikan operasi compact. Gunakan event ini untuk bereaksi terhadap state baru yang sudah di-compact, misalnya untuk mencatat ringkasan yang dihasilkan atau memperbarui state 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 pergantian model yang diminta oleh Anda atau klien. Gunakan untuk memblokir pergantian, meminta konfirmasi, atau menampilkan biaya pergantian sebelum terjadi.

PreModelSwitch memerlukan Claude Code v2.1.251 atau yang 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 pergantian yang dilakukannya sendiri, seperti fallback model otomatis atau memulihkan model ketika Anda melanjutkan sesi. Perubahan tersebut hanya mencapai PostModelSwitch.

Claude Code membandingkan matcher dengan nama kanonis model yang menjadi tujuan pergantian sesi, dengan mengabaikan sufiks [1m] apa pun. 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 diketahui oleh LLM gateway Anda, Claude Code menjalankan setiap hook PreModelSwitch terlepas dari matcher-nya. Oleh karena itu, hook yang memblokir harus memeriksa to_model dari input-nya alih-alih hanya mengandalkan matcher.

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

[tab] macOS/Linux

Perintah ini memeriksa to_model dengan jq:

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

[tab] Windows (PowerShell)

Daftarkan hook command yang menjalankan skrip melalui PowerShell:

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

Simpan skrip ini ke .claude/hooks/block-opus-46.ps1 di proyek Anda:

$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 pergantian, 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 pergantian 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 pergantian, meminta pengguna untuk mengonfirmasinya, atau membiarkannya berlanjut. Exit code 2 atau decision: "block" tingkat atas membatalkan pergantian.

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 tersebut:

Hanya /model dalam sesi interaktif yang dapat menampilkan dialog "ask". Pada setiap surface lain, 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 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.

Timeout PreModelSwitch dan exit code lainnya

Hook PreModelSwitch yang tidak merespons sebelum timeout-nya memblokir peralihan. Timeout default untuk event ini adalah 30 detik.

Exit code selain 0 atau 2 tanpa output JSON yang valid merupakan error yang tidak memblokir, sehingga peralihan tetap berlangsung, kecuali untuk hook yang kegagalannya memblokir peralihan.

PostModelSwitch

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

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

• Pergantian 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 ketika Anda melanjutkan sesi

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

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

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

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

Untuk 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 ketika 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 pergantian. 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 berikutnya. Jika model berubah beberapa kali sebelum permintaan berikutnya, Claude Code hanya mengirimkan output untuk model target pergantian terakhir.

SessionEnd

Berjalan ketika sesi Claude Code berakhir. Berguna untuk tugas pembersihan, mencatat statistik sesi, atau menyimpan state 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 reason di atas untuk semua nilai.

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

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

Hook SessionEnd memiliki timeout default 1,5 detik. Ini berlaku ketika 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 dalam konfigurasi hook tersebut. Anggaran keseluruhan naik secara otomatis untuk menyamai 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 ketika 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.

Untuk hook lengkap beserta entri pengaturan dan skripnya, lihat Menjawab permintaan formulir dari skrip.

Field matcher dicocokkan dengan nama server MCP.

Input Elicitation

Selain field input umum, hook Elicitation menerima 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

Hook Elicitation dapat menjawab permintaan atas nama pengguna, menolak atau membatalkannya, atau menyerahkannya ke dialog. Untuk menjawab, menolak, atau membatalkan, keluar dengan 0 dan cetak objek hookSpecificOutput dengan action. Server menerima jawaban Anda dan tidak ada dialog yang muncul. Setiap baris tabel ini menunjukkan apa yang dikembalikan untuk satu hasil dan apa yang diterima server MCP:

Output ini menjawab permintaan mode formulir yang ditampilkan di Input Elicitation. Kunci dalam content adalah nama properti dari requested_schema permintaan tersebut:

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

Output ini menolak permintaan:

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "decline"
  }
}

Di dialog, memilih Decline mengirim decline dan menekan Esc mengirim cancel, jadi kembalikan yang ingin Anda tampilkan ke server.

Untuk permintaan mode URL, hook yang mengembalikan accept melewati dialog, sehingga URL tidak pernah dibuka.

Claude Code membuang reason, systemMessage, dan continue dari output JSON hook Elicitation, apa pun action yang Anda kembalikan.

Cara lain untuk menolak elicitation

Hook Anda juga dapat menolak dengan cara berikut. Server menerima decline yang sama seperti untuk "action": "decline":

• Keluar dengan kode 2: Claude Code mengabaikan hookSpecificOutput yang dicetak oleh hook yang sama
• Mencetak "decision": "block" tingkat atas: block menimpa action dalam output yang sama

Ketika beberapa hook cocok dengan permintaan yang sama, penolakan dari salah satunya menimpa accept atau cancel dari hook lain.

Skrip ini menolak permintaan mode URL dan menyerahkan permintaan formulir ke dialog:

#!/bin/bash
if [ "$(jq -r '.mode')" = "url" ]; then
  exit 2
fi

Baik pengguna maupun server tidak melihat alasan hook Anda menolak, karena Claude Code tidak menampilkan stderr atau reason Anda.

Claude Code mengabaikan decision tingkat atas dari hook Elicitation dan ElicitationResult sejak v2.1.105 hingga perbaikan di v2.1.284.

Menjawab permintaan formulir dari skrip

Contoh ini menjawab satu pertanyaan berulang atas nama pengguna. Server MCP bernama issue-tracker meminta kunci proyek dalam formulir, dan hook mengisinya dengan DOCS. Skrip menerima ketika project_key adalah satu-satunya field formulir. Untuk permintaan lainnya, skrip tidak mencetak apa pun, sehingga dialog muncul.

[tab] macOS/Linux

Daftarkan hook command untuk event ini di file pengaturan Anda, dengan nama server sebagai matcher:

{
  "hooks": {
    "Elicitation": [
      {
        "matcher": "issue-tracker",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Simpan skrip ini ke .claude/hooks/answer-project-key.sh di proyek Anda dan jadikan dapat dieksekusi dengan chmod +x:

#!/bin/bash
input=$(cat)
fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")

if [ "$fields" = '["project_key"]' ]; then
  jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'
fi

[tab] Windows (PowerShell)

Daftarkan hook command yang menjalankan skrip melalui PowerShell, dengan nama server sebagai matcher:

{
  "hooks": {
    "Elicitation": [
      {
        "matcher": "issue-tracker",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"
            ]
          }
        ]
      }
    ]
  }
}

Simpan skrip ini ke .claude/hooks/answer-project-key.ps1 di proyek Anda:

$request = [Console]::In.ReadToEnd() | ConvertFrom-Json
$fields = @($request.requested_schema.properties.PSObject.Properties.Name)

if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {
  @{
    hookSpecificOutput = @{
      hookEventName = "Elicitation"
      action = "accept"
      content = @{ project_key = "DOCS" }
    }
  } | ConvertTo-Json -Depth 3
}