SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor

Hook Claude Code: Event, Exit Code 2, dan Keamanan

Pahami hook Claude Code yang tetap berjalan tanpa persetujuan model, lokasi konfigurasinya, event pemicu, dampak exit code 2, serta risiko keamanannya.

Apa itu hook Claude Code

Hook Claude Code adalah perintah shell yang dijalankan sendiri oleh Claude Code pada titik-titik tertentu dalam siklus hidupnya. Inilah perbedaan utama antara hook dan file aturan. Instruksi dalam CLAUDE.md hanyalah saran, dan model akan menimbangnya terhadap semua hal lain dalam konteksnya. Hook adalah kode, dan ia akan berjalan terlepas dari apakah model setuju atau tidak. Jika agen Anda terus mengabaikan formatter yang sudah Anda beritahukan dua kali, Anda tidak memerlukan instruksi yang lebih tegas. Anda memerlukan hook.

Mekanismenya sederhana. Anda mendaftarkan perintah dalam file pengaturan di bawah nama event. Saat event tersebut dipicu, Claude Code menjalankan perintah Anda dan menulis data event ke input standar (stdin) sebagai JSON (JavaScript object notation). Perintah Anda membaca data tersebut, melakukan tugasnya, dan menjawab dengan status keluar. Status keluar 2 dari hook PreToolUse akan membatalkan pemanggilan tool sebelum dijalankan, dan apa pun yang ditulis skrip Anda ke error standar (stderr) akan dikembalikan ke model sebagai alasannya, kecuali jika hook tersebut juga mencetak JSON yang berisi keputusan pemblokiran, yang alasannya akan lebih diutamakan.

Nama event dan nama field di sini berasal dari referensi hook Claude Code, yang diperiksa pada 12 November 2026. Area ini berkembang dengan cepat, jadi periksa referensi untuk versi Anda sendiri sebelum menyalin JSON dari postingan blog mana pun, termasuk yang satu ini. Cetak milik Anda dengan claude --version.

Lokasi konfigurasi hook

Hook adalah blok JSON dalam file pengaturan. Hook dapat disimpan di enam lokasi, dan cakupan file menentukan cakupan hook tersebut.

  • ~/.claude/settings.json: semua project di mesin Anda, dan tidak di mesin pengguna lain.
  • .claude/settings.json: satu project, di-commit ke repository, sehingga setiap orang yang melakukan clone akan mendapatkan hook tersebut.
  • .claude/settings.local.json: satu project, hanya di mesin Anda.
  • Pengaturan kebijakan terkelola: berlaku di seluruh organisasi dan ditetapkan oleh administrator.
  • hooks/hooks.json di dalam plugin: aktif selama plugin tersebut diaktifkan.
  • Frontmatter skill atau subagent. Hook milik skill tetap aktif selama sisa session setelah skill dipanggil, sedangkan hook milik subagent aktif selama subagent tersebut berjalan.

Entri hook dari file-file ini digabungkan, bukan saling menimpa. File pengaturan project menambahkan hook-nya ke hook dalam pengaturan pengguna, bukan menggantikannya. Karena itu, satu event dapat memiliki beberapa hook dari beberapa file. Pengaturan "disableAllHooks": true menonaktifkan hook, dengan satu pengecualian: hook dari pengaturan kebijakan terkelola tetap berjalan, kecuali pengaturan tersebut juga diterapkan dalam pengaturan terkelola.

Jalankan /hooks di dalam session untuk menampilkan semua hook yang saat ini terdaftar, dikelompokkan berdasarkan event, beserta file sumber dan matcher masing-masing. Menu ini hanya dapat dibaca, sehingga Anda harus mengubah hook dengan mengedit file pengaturan. File watcher biasanya mendeteksi perubahan tersebut tanpa perlu restart.

Event hook apa saja yang tersedia di Claude Code

Referensi hook mencantumkan tiga puluh tiga event, mulai dari SessionStart hingga SessionEnd, yang mencakup kompresi (compaction), subagen, worktree, dan file konfigurasi. Pekerjaan server hanya menggunakan sebagian kecil di antaranya.

  • PreToolUse: sebelum pemanggilan tool dieksekusi, kecuali EndConversation. Ini adalah event yang dapat memblokir proses.
  • PostToolUse: setelah pemanggilan tool berhasil, kecuali EndConversation. PostToolUseFailure akan aktif jika pemanggilan gagal, jadi hook yang harus memantau setiap hasil perlu menggunakan keduanya.
  • PermissionRequest: saat pemanggilan tool memerlukan keputusan izin, yaitu momen ketika prompt persetujuan akan muncul.
  • UserPromptSubmit: saat Anda mengirimkan prompt, sebelum Claude memprosesnya. Output stdout teks biasa dari hook yang berhasil akan ditambahkan ke konteks model.
  • SessionStart dan SessionEnd: pada setiap akhir sesi. SessionStart juga aktif setelah kompresi, di bawah nilai matcher compact.
  • Stop: saat Claude selesai memberikan respons. Ini terjadi sekali per giliran, bukan sekali per tugas yang selesai.

Pada event yang mendukung matcher, sebuah grup dapat membawa matcher yang menentukan kejadian mana yang menjalankan hook tersebut. Pada event tool, matcher memfilter berdasarkan nama tool, sehingga "Edit|Write" hanya akan aktif pada pengeditan file dan tidak pada yang lain. Matcher bersifat case-sensitive. Matcher yang kosong akan aktif pada setiap kejadian. Tool dari server MCP (model context protocol) diberi nama mcp__<server>__<tool>, sehingga matcher "mcp__github__.*" akan menangkap tool dari satu server saja dan membiarkan yang lainnya.

Hook Stop memiliki jebakan yang perlu diketahui sebelum Anda menulisnya. Hook Stop yang memblokir akan mengirim model kembali bekerja, dan secara default Claude Code akan mengambil alih blok berikutnya setelah delapan kali kelanjutan berturut-turut, dengan hitungan yang diatur ulang setiap kali Claude memanggil tool. Baca field stop_hook_active dari input hook dan lakukan exit 0 saat nilainya true, jika tidak, hook Anda dapat terus mengirim Claude kembali bekerja.

Data yang diterima hook melalui stdin

Saat Claude akan menjalankan npm test, hook PreToolUse pada Bash membaca data berikut melalui stdin:

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Kolom input yang umum mencakup session_id, cwd, transcript_path, dan hook_event_name; permission_mode tidak dikirim pada setiap event. Event tool menambahkan tool_name, tool_input, dan tool_use_id. Event lain memiliki kolomnya sendiri: UserPromptSubmit mendapatkan teks prompt, sedangkan SessionStart mendapatkan source dari startup, resume, clear, compact, atau fork.

jq adalah cara umum untuk membaca data ini di dalam shell script, dan image server minimal tidak menyertakannya. Instal terlebih dahulu dengan sudo apt install -y jq di Ubuntu dan Debian.

Status keluar terhadap pemanggilan tool yang sedang berlangsung

Ada tiga hasil.

  • Exit 0 berarti berhasil, dan semua bidang keputusan JSON yang valid tetap berlaku, termasuk pemblokiran atau penolakan. Pada PreToolUse, exit 0 tanpa keputusan bukan berarti persetujuan, dan alur izin normal tetap berjalan. Pada UserPromptSubmit, UserPromptExpansion, SessionStart, dan PostModelSwitch, stdout teks biasa ditambahkan ke konteks model. Pada sebagian besar event lainnya, stdout hanya masuk ke debug log.
  • Exit 2 memblokir tindakan pada event yang dapat diblokir, termasuk PreToolUse, dan stderr menjadi pesan yang menyertai pemblokiran tersebut, kecuali output JSON berisi keputusan pemblokiran; dalam hal itu, alasan dari keputusan JSON menjadi prioritas. Pihak yang membaca pesan tersebut bergantung pada event. Pada PreToolUse dan Stop, model melihatnya sebagai alasan. Pada UserPromptSubmit dan PreModelSwitch, pesan ditampilkan kepada Anda dan tidak ditambahkan ke konteks model. Pada PostToolUse dan PostToolUseFailure, yang tidak dapat diblokir, pemblokiran diabaikan, tetapi stderr tetap diteruskan kepada model sebagai umpan balik. Pada sebagian besar event lain yang tidak dapat diblokir, stderr hanya ditampilkan kepada Anda atau diabaikan. Pada Stop, SubagentStop, TaskCompleted, dan hook UserPromptSubmit milik plugin, exit 2 dengan stdout kosong dan error file yang tidak ditemukan pada stderr diperlakukan sebagai error yang tidak memblokir.
  • Kode exit lainnya dengan stdout teks biasa atau kosong biasanya merupakan error yang tidak memblokir. Transkrip menampilkan pemberitahuan error hook yang memuat baris pertama stderr setelah teks Failed with non-blocking status code:. JSON yang valid tetap dapat menentukan hasil pada event seperti PreToolUse, kecuali kegagalan hook memblokir tindakan. WorktreeCreate gagal pada setiap exit nonzero, dan WorktreeRemove gagal pada exit nonzero jika direktori masih ada setelahnya.

Untuk tindakan selain memblokir atau tidak melakukan apa pun, gunakan exit 0 dan cetak objek JSON ke stdout. Hook PreToolUse mengambil keputusan dengan permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" melewati prompt interaktif jika aturan izin dan persyaratan persetujuan tool mengizinkannya, "deny" membatalkan pemanggilan dan mengirimkan alasannya kepada model, sedangkan "ask" meminta konfirmasi. Gunakan satu gaya untuk setiap hook. Mencampur exit 2 dengan keputusan JSON pada stdout tetap mempertahankan pemblokiran, meskipun JSON menyatakan "allow".

Jika beberapa hook cocok dengan satu event, hook tersebut berjalan secara paralel. Hook prompt dan agent dibatasi hingga dua belas hook yang berjalan secara bersamaan. deny dari satu hook tidak menghentikan hook lain yang terkait. Dengan demikian, hook logging tetap menulis barisnya sementara hook guardrail menolak pemanggilan yang sama. Untuk PreToolUse, Claude Code kemudian menggabungkan semua jawaban dan mempertahankan jawaban yang paling ketat, dengan urutan deny, defer, ask, allow.

Contoh 1: blokir perintah destruktif sebelum dijalankan

Simpan ini sebagai .claude/hooks/block-destructive.sh di project Anda:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

Jadikan file tersebut dapat dieksekusi, lalu daftarkan pada PreToolUse di .claude/settings.json:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

Uji script secara manual sebelum Anda mempercayainya, karena hook yang crash saat memproses inputnya sendiri biasanya gagal secara terbuka ketika onFailure tidak ditetapkan. Pada Windows tanpa Git Bash, hook perintah dalam bentuk shell PreToolUse atau PermissionRequest yang gagal justru dapat memblokir pemanggilan tool:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Anda akan melihat baris Blocked by policy: di stderr dan exit code 2. Berikan perintah yang tidak berbahaya seperti ls -la, lalu Anda seharusnya tidak melihat output apa pun dan mendapatkan exit code 0. Dalam sebuah sesi, pemanggilan yang ditolak muncul di transcript bersama pesan Anda sebagai alasannya, lalu model membaca pesan tersebut dan menyesuaikan tindakannya.

Satu karakteristik membuat pendekatan ini layak digunakan: hook PreToolUse dijalankan sebelum pemeriksaan permission mode, dalam setiap permission mode, sehingga penolakan tetap berlaku bahkan dengan bypassPermissions. Inilah yang membuat hook berguna bersama mode otomatis Claude Code dan pengaturan permission-nya, ketika prompt dikurangi tetapi hook tetap dijalankan.

Pahami batasannya. Pencocokan pola pada string perintah merupakan guardrail agar agent tidak bertindak ceroboh. Namun, ini bukan batasan terhadap agent yang bertindak secara cerdik, karena perintah yang sama dapat ditulis dalam bentuk yang tidak pernah dilihat oleh grep. Aturan yang tegas harus diterapkan dalam permission system dan pada account yang digunakan untuk menjalankan proses tersebut.

Contoh 2: format dan lint setelah setiap pengeditan

PostToolUse dengan matcher Edit|Write berjalan setelah salah satu dari kedua alat pengeditan file tersebut berhasil. Simpan konfigurasi ini sebagai .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Minta Claude menambahkan fungsi dengan indentasi yang buruk ke file Python, lalu buka file tersebut. Fungsi itu akan muncul dalam format yang benar. Ini membuktikan bahwa hook berjalan, karena hook yang berhasil tidak menampilkan apa pun dalam percakapan.

Exit 2 di sini tidak membatalkan apa pun. PostToolUse berjalan setelah tool selesai dieksekusi, sehingga hasil pengeditan tetap tersimpan di disk. Exit 2 membuat output ruff check dikirim ke model sebagai umpan balik, sehingga model memperbaiki error yang baru saja dibuatnya sebelum melanjutkan. Inilah perbedaan antara kegagalan lint yang baru ditemukan saat commit dan kegagalan yang diperbaiki agent pada giliran yang sama.

Ada dua batasan matcher yang perlu diperhatikan. Edit|Write tidak melihat file yang diubah oleh perintah shell, dan Claude cukup sering menulis file melalui Bash sehingga celah ini memang nyata. Untuk cakupan setiap pemanggilan, cocokkan Bash juga dan minta skrip mencantumkan file yang berubah dengan git status --porcelain. Untuk cakupan sekali per giliran, letakkan pemindaian tersebut dalam hook Stop.

Contoh 3: mencatat setiap pemanggilan alat untuk audit

Matcher kosong pada PostToolUse akan aktif pada setiap pemanggilan alat yang berhasil kecuali EndConversation. Mengirim catatan ke jurnal sistem alih-alih ke file di direktori home tidak menjamin catatan tersebut aman dari jangkauan shell agen itu sendiri: akses bergantung pada izin akun. Pengguna dapat membaca jurnal pribadi per-pengguna mereka, dan root serta anggota systemd-journal, adm, atau wheel dapat membaca semua file jurnal:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

Baca kembali dengan journalctl -t claude-code -o cat | tail -n 5. Dengan izin untuk membaca catatan, Anda seharusnya melihat satu baris JSON per pemanggilan alat yang berhasil selain EndConversation, dengan yang terbaru berada di urutan terakhir. Jika tidak ada yang muncul, periksa akses jurnal serta apakah hook telah berjalan; bagian pemecahan masalah di bawah ini membahas hook tersebut.

Tambahkan blok yang sama di bawah PostToolUseFailure untuk menangkap pemanggilan yang gagal, karena PostToolUse hanya aktif saat berhasil dan perintah yang gagal biasanya adalah yang paling penting. Alasan penggunaan logger alih-alih menambahkan ke file di direktori home Anda adalah kepemilikan: hook berjalan sebagai pengguna yang sama dengan shell agen, sehingga apa pun yang dapat ditambahkan oleh pengguna tersebut, dapat juga dihapus oleh pengguna tersebut. Jurnal ditulis oleh systemd-journald; melindunginya dari penghapusan tetap bergantung pada hak istimewa akun agen.

Berapa lama hook dapat berjalan

GrafikDefault hook timeout in seconds, by hook type and event
Data di balik grafik ini
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

Sebuah command hook mendapatkan 600 detik secara default, yaitu sepuluh menit. Beberapa event membatasi durasi ini secara ketat. Hook SessionEnd berbagi anggaran waktu sebesar 1,5 detik untuk semuanya, sehingga pembersihan akhir sesi harus dilakukan dengan cepat, meskipun menetapkan timeout yang lebih lama pada hook di file pengaturan Anda akan meningkatkan anggaran bersama tersebut hingga maksimal 60 detik.

Perintah sinkron, hook HTTP, atau tool hook MCP yang mencapai batas waktu (timeout) akan dibatalkan dan biasanya tidak menghasilkan keputusan; pada PreModelSwitch, timeout akan memblokir switch tersebut. Untuk guardrail PreToolUse, timeout biasanya membiarkan pemanggilan tool berlanjut ke alur izin normal, dengan pengecualian Windows di atas jika onFailure tidak diatur. Oleh karena itu, buatlah skrip guardrail tetap ringkas. Sejak rilis 2.1.295, Anda dapat membalikkan default tersebut pada hook command atau http dengan "onFailure": "block", yang mengubah timeout, crash, atau kode keluar yang tidak terduga menjadi blokir, meskipun hal ini tidak berpengaruh pada hook Stop, SubagentStop, TaskCompleted, TeammateIdle, atau command hook latar belakang. Untuk pekerjaan lambat yang tidak ditunggu oleh siapa pun, seperti mengirim log ke suatu tempat, atur "async": true agar hook berjalan di latar belakang tanpa menahan pemanggilan tool.

Hook, file aturan, skill, dan server MCP

Empat hal ini sering tertukar karena semuanya mengubah perilaku agen. Hanya satu yang tidak lagi bersifat saran.

File aturan (CLAUDE.md, atau file di bawah .claude/rules/) adalah teks yang dimuat ke dalam konteks model. File ini membentuk perilaku, tetapi tidak menegakkan apa pun. Dalam percakapan panjang, diff besar, dan permintaan pengguna baru, satu baris di dalamnya dapat terabaikan. Inilah mekanisme umum di balik agen yang mengabaikan instruksi yang Anda tulis.

Skill adalah folder berisi instruksi dan skrip yang dimuat model ketika model menilai skill tersebut relevan. Penilaian itu merupakan tujuan skill, sekaligus batasannya: model tetap mengambil keputusan. Anda dapat melihat kedua sisi ini pada skill seperti Ponytail, yang mengarahkan agen untuk menerapkan perubahan terkecil yang berfungsi, karena skill tersebut membentuk cara seluruh tugas dikerjakan dengan cara yang tidak dapat dilakukan hook, dan hanya selama model memilih untuk memuatnya.

Server MCP (model context protocol) memberi model alat baru untuk dipanggil. Server ini memperluas hal-hal yang dapat dijangkau agen. Server ini tidak membuat agen menggunakan alat apa pun, dan merupakan proses terpisah yang harus Anda operasikan. Pengoperasian tersebut merupakan tugas tersendiri. Lihat menjalankan server MCP pada VPS.

Hook adalah satu-satunya dari keempat hal ini yang berjalan tanpa dipilih oleh model. Gunakan file aturan untuk preferensi dan skill untuk prosedur yang harus diikuti model ketika prosedur tersebut berlaku. Gunakan hook untuk langkah yang harus dijalankan setiap kali, atau untuk hal yang tidak boleh terjadi. Perbandingan yang lebih mendalam, termasuk kondisi ketika skill lebih tepat daripada file aturan, tersedia di perbandingan skill, MCP, dan file aturan.

Plugin adalah mekanisme pengemasan, bukan mekanisme kelima. Plugin menggabungkan hook dan skill menjadi satu unit yang dapat diinstal. Dengan cara ini, tim dapat menerapkan guardrail yang sama pada setiap mesin. Lihat cara kerja plugin Claude Code.

Keputusan keamanan pada VPS bersama

Hook adalah kode yang dipicu oleh agen, dan ia berjalan sebagai pengguna yang memulai Claude Code. Hook tersebut mewarisi izin file dan lingkungan pengguna tersebut. Pada laptop, ini adalah masalah alur kerja. Pada VPS tempat agen berjalan tanpa pengawasan, ini adalah masalah keamanan dengan empat aspek praktis.

Hook dalam repositori adalah kode yang tidak Anda tulis. .claude/settings.json di-commit, jadi melakukan kloning repositori dan memulai sesi di dalamnya dapat mendaftarkan hook yang disertakan dalam repositori tersebut. Dalam sesi interaktif, Claude Code membatasi hook proyek di balik dialog kepercayaan ruang kerja untuk folder tersebut, yang berarti menerima kepercayaan adalah momen saat Anda memutuskan untuk menjalankannya. Baca blok hooks terlebih dahulu. Sesi claude -p atau SDK, yang merupakan cara agen tanpa pengawasan biasanya berjalan, tidak pernah menampilkan dialog tersebut dan menganggap folder sebagai tepercaya, sehingga hook repositori berjalan tanpa bertanya. Tinjau file .claude/-nya sebelum Anda membuat skrip untuknya, atau jalankan dengan --settings '{"disableAllHooks": true}'.

Hook melihat input tool secara penuh. Hook audit yang mencatat tool_input menulis setiap argumen dari setiap perintah ke dalam log, termasuk token apa pun yang kebetulan ada pada baris perintah. Log tersebut kemudian memerlukan perlindungan yang sama dengan rahasia itu sendiri, yang merupakan bagian dari masalah yang lebih luas mengenai menjaga rahasia agar tidak terjangkau oleh agen AI.

Hook dapat menulis ke dalam konteks model. stdout teks biasa dari hook SessionStart atau UserPromptSubmit yang berhasil akan ditambahkan ke percakapan. Hook yang menyalurkan teks dari luar, pelacak masalah, atau file log, berarti memberikan teks yang tidak tepercaya kepada model seolah-olah Anda sendiri yang mengetiknya. Hook yang meneruskan catatan dari sesi Claude Code lain pada VPS yang sama melakukan hal yang sama, dan output satu agen tidak memiliki klaim lebih besar atas kepercayaan Anda daripada pelacak masalah tersebut. Perlakukan stdout tersebut sebagai input, bukan sebagai output.

Hak akses adalah kontrol yang sebenarnya. Jalankan agen sebagai pengguna khusus tanpa hak akses (unprivileged) dengan hanya aturan sudo yang diperlukannya. Penolakan PreToolUse layak dimiliki, dan itu adalah upaya terbaik berdasarkan desain: referensi menyatakan hal yang sama tentang filter if dan menyarankan Anda untuk menggunakan sistem izin saat Anda memerlukan penolakan keras. Aturan izin dan akun tempat proses berjalan adalah bagian yang bertahan di bawah tekanan.

Satu properti tetap berlaku dalam setiap mode izin. Hook PreToolUse dipicu sebelum pemeriksaan mode izin dalam setiap mode izin, sehingga hook yang mengembalikan deny akan memblokir tool bahkan di bawah bypassPermissions. Hook dapat memperketat apa yang diizinkan oleh aturan izin. Hook tidak dapat melonggarkannya. Pengecualiannya adalah mod. Pada mesin tanpa pengaturan terkelola dan tanpa file managed-mcp.json, dalam sesi yang tidak masuk melalui /login ke paket Team atau Enterprise, mod terinstal yang menangani tool.check dapat menyetujui panggilan yang diblokir oleh hook PreToolUse Anda. Dengan pengaturan terkelola, file managed-mcp.json, atau /login Team atau Enterprise sebagai kredensial sesi, panggilan yang diblokir oleh hook PreToolUse akan tetap diblokir secara default, dari file pengaturan mana pun hook tersebut berasal. Sesi yang berjalan pada API key atau CLAUDE_CODE_OAUTH_TOKEN jangka panjang, yang merupakan cara banyak server menjalankannya, dihitung sebagai tidak masuk meskipun login tersimpan. Periksa apa yang dapat diubah oleh mod Claude Code sebelum Anda menginstalnya di server.

Mengapa hook saya tidak dijalankan?

Ikuti langkah-langkah berikut secara berurutan. Setiap langkah menjelaskan gejala yang akan Anda lihat.

  • Jalankan /hooks dan periksa apakah hook muncul pada event yang Anda harapkan. Hook yang tidak muncul di menu biasanya menunjukkan bahwa file pengaturan memiliki kesalahan sintaks JSON, karena koma di akhir dan komentar tidak diizinkan, atau file tersebut tidak berada di salah satu dari enam lokasi di atas.
  • Bandingkan matcher dengan nama tool secara tepat. Matcher peka huruf besar-kecil, sehingga "bash" tidak pernah cocok dengan tool Bash.
  • Jalankan skrip secara manual dengan input contoh, seperti pada contoh 1 di atas. Kode keluar yang tidak Anda harapkan menunjukkan bug dalam skrip Anda. Periksa stdout-nya juga, karena JSON yang valid tetap dapat memberikan keputusan pada event seperti PreToolUse.
  • Pesan jq: command not found berarti jq tidak tersedia pada mesin tersebut. command not found untuk skrip Anda sendiri berarti path tidak dapat ditemukan, jadi gunakan ${CLAUDE_PROJECT_DIR} atau path absolut. Jika skrip sama sekali tidak pernah dijalankan, kemungkinan skrip tersebut tidak memiliki izin eksekusi.
  • Hook mencetak JSON yang valid, tetapi tidak terjadi apa-apa. Di macOS dan Linux, hook berbentuk shell dijalankan melalui sh -c dalam shell noninteraktif, tetapi beberapa konfigurasi tetap memuat profile Anda, misalnya BASH_ENV yang menunjuk ke ~/.bashrc. Jika profile tersebut mencetak banner, banner akan ditambahkan di awal JSON Anda. Stdout tidak lagi dimulai dengan {, sehingga Claude Code membaca seluruhnya sebagai teks biasa dan mengabaikan keputusan tersebut. Karena hook keluar dengan kode 0, transcript tidak menampilkan error. Pada sebagian besar event, teks tersebut hanya masuk ke debug log. Namun, pada UserPromptSubmit, UserPromptExpansion, SessionStart, dan PostModelSwitch, teks tersebut ditambahkan ke konteks model, termasuk banner. Bungkus setiap echo dalam profile Anda agar hanya dijalankan di shell interaktif.
  • Jika masalah masih belum teratasi, mulai sesi dengan claude --debug-file /tmp/claude.log dan jalankan tail -f /tmp/claude.log di terminal kedua. Debug log mencatat hook yang cocok, kode keluar yang dikembalikan masing-masing hook, serta semua data yang ditulisnya ke stdout dan stderr.

FAQ

Apa perbedaan antara hook Claude Code dan instruksi CLAUDE.md?

Instruksi CLAUDE.md adalah teks dalam konteks model. Instruksi ini bersaing untuk mendapatkan perhatian bersama percakapan dan permintaan saat ini, sehingga model dapat mempertimbangkan prioritasnya. Hook adalah perintah shell yang dijalankan Claude Code pada titik tertentu dalam siklus hidupnya. Karena itu, hook dijalankan pada setiap kemunculan event terkait, terlepas dari keputusan model. Gunakan instruksi untuk menetapkan preferensi. Gunakan hook untuk langkah yang harus selalu dijalankan atau tindakan yang tidak boleh dijalankan.

Bagaimana cara menghentikan Claude Code agar tidak menjalankan perintah shell tertentu?

Daftarkan hook PreToolUse dengan matcher Bash yang membaca perintah dari .tool_input.command, menulis alasan ke stderr, lalu keluar dengan kode 2. Claude Code membatalkan pemanggilan tersebut dan menampilkan alasan Anda kepada model. Proses ini terjadi sebelum pemeriksaan permission mode, sehingga penolakan tetap berlaku dalam mode bypassPermissions. Pencocokan pola pada string perintah merupakan pengamanan, bukan batas keamanan. Perintah yang sama dapat ditulis dalam bentuk yang tidak cocok dengan pola. Karena itu, gunakan juga aturan permission dan akun tanpa hak istimewa.

Hook saya mencetak JSON yang valid, tetapi tidak terjadi apa-apa. Mengapa?

Periksa shell profile Anda untuk mengetahui apakah ada teks yang dicetak sebelum JSON. Pada macOS dan Linux, hook tanpa field args dijalankan melalui sh -c. Dalam konfigurasi yang masih memuat profile, misalnya BASH_ENV yang mengarah ke ~/.bashrc, profile yang mencetak banner akan menulisnya ke stdout sebelum JSON Anda. Karena output tidak lagi diawali {, Claude Code memperlakukan seluruh output sebagai teks biasa dan mengabaikan keputusan tersebut. Karena hook keluar dengan kode 0, transcript juga tidak menampilkan error. Lindungi setiap echo dalam profile dengan pemeriksaan interactive shell, lalu pastikan perbaikannya dengan membaca debug log dari claude --debug-file /tmp/claude.log.

Apakah aman menjalankan hook Claude Code pada server bersama?

Hook dijalankan sebagai user yang memulai Claude Code, dengan permission file milik user tersebut. Karena itu, hook dapat melakukan apa pun yang dapat dilakukan akun tersebut. Dua kebiasaan berikut mencakup sebagian besar risikonya: jalankan agent sebagai akun khusus tanpa hak istimewa dengan kebijakan sudo yang ketat, lalu baca blok hooks dari setiap repository sebelum menerima dialog kepercayaan workspace atau menjalankan claude -p di dalamnya. Hook project disertakan dalam .claude/settings.json, dan mode -p tidak pernah menampilkan dialog tersebut. Atur "disableAllHooks": true dalam settings file untuk menonaktifkan hook, kecuali managed hook yang mengharuskan pengaturan ini pada level managed. Pengaturan project false dapat menimpa pengaturan user true.

Apakah artikel ini bermanfaat?