Claude Code Hooks: Acara, Lokasi dan Kod Keluar 2
Ketahui lokasi hook Claude Code, acara yang mencetuskannya, kesan status keluar 2 terhadap panggilan alat dan risiko keselamatan apabila kod berjalan tanpa persetujuan model.
Apakah itu hook Claude Code
Hook Claude Code ialah perintah shell yang dijalankan oleh Claude Code sendiri pada titik tetap dalam kitaran hayatnya. Itulah perbezaan utama antara hook dan fail peraturan. Arahan dalam CLAUDE.md hanyalah nasihat, dan model akan menimbangkannya berbanding perkara lain dalam konteksnya. Hook ialah kod, dan ia akan berjalan sama ada model bersetuju atau tidak. Jika ejen anda terus melangkau pemformat yang anda tetapkan sebanyak dua kali, anda tidak memerlukan arahan yang lebih tegas. Anda memerlukan hook.
Mekanismenya ringkas. Anda mendaftarkan perintah dalam fail tetapan di bawah nama peristiwa. Apabila peristiwa itu dicetuskan, Claude Code menjalankan perintah anda dan menulis data peristiwa tersebut ke input standard (stdin) sebagai JSON (JavaScript object notation). Perintah anda membaca data tersebut, melaksanakan tugasnya, dan menjawab dengan status keluar. Status keluar 2 daripada hook PreToolUse akan membatalkan panggilan alat sebelum ia dijalankan, dan apa sahaja yang ditulis oleh skrip anda ke ralat standard (stderr) akan diserahkan kembali kepada model sebagai alasan, melainkan hook tersebut turut mencetak JSON yang mengandungi keputusan sekatan, yang mana alasannya akan diutamakan.
Nama peristiwa dan nama medan di sini diambil daripada rujukan hook Claude Code, yang disemak pada 12 November 2026. Maklumat ini berubah dengan pantas, jadi semak rujukan untuk versi anda sendiri sebelum anda menyalin JSON daripada mana-mana catatan blog, termasuk yang ini. Cetak milik anda dengan claude --version.
Lokasi konfigurasi hook
Hook ialah blok JSON dalam fail tetapan. Terdapat enam lokasi yang boleh menyimpan hook, dan skop fail tersebut menentukan skop hook berkenaan.
~/.claude/settings.json: setiap projek pada mesin anda, dan bukan pada mesin orang lain..claude/settings.json: satu projek, yang dikomit ke dalam repositori, supaya sesiapa yang melakukan clone akan mendapat hook tersebut..claude/settings.local.json: satu projek, hanya pada mesin anda.- Tetapan polisi terurus: seluruh organisasi, ditetapkan oleh pentadbir.
hooks/hooks.jsondi dalam pemalam, aktif selagi pemalam tersebut didayakan.- Frontmatter skill atau subagent. Hook bagi sesuatu skill kekal aktif sepanjang sesi selepas skill tersebut dipanggil, manakala hook subagent aktif selagi subagent tersebut berjalan.
Entri hook daripada fail-fail ini akan digabungkan dan bukannya saling menimpa. Fail tetapan projek menambah hook miliknya kepada hook dalam tetapan pengguna dan tidak menggantikannya, jadi satu peristiwa boleh mengandungi beberapa hook daripada beberapa fail. Tetapan "disableAllHooks": true akan mematikan hook tersebut, dengan satu pengecualian: hook daripada tetapan polisi terurus akan terus berjalan melainkan tetapan tersebut turut digunakan dalam tetapan terurus.
Jalankan /hooks di dalam sesi untuk menyenaraikan setiap hook yang sedang didaftarkan, dikumpulkan mengikut peristiwa, berserta fail sumber dan pemadanan (matcher) bagi setiap satunya. Menu ini adalah baca sahaja, jadi anda perlu menukar hook dengan menyunting fail tetapan. Pemerhati fail (file watcher) biasanya akan mengesan suntingan tersebut tanpa perlu melakukan mulakan semula (restart).
Peristiwa hook Claude Code yang wujud
Rujukan hook menyenaraikan tiga puluh tiga peristiwa, daripada SessionStart hingga SessionEnd, yang meliputi pemadatan, subagen, worktree dan fail konfigurasi. Kerja pentadbiran pelayan menggunakan beberapa daripadanya.
PreToolUse: sebelum panggilan alat dilaksanakan, kecualiEndConversation. Peristiwa ini boleh menyekat panggilan.PostToolUse: selepas panggilan alat berjaya, kecualiEndConversation.PostToolUseFailurepula dicetuskan apabila panggilan gagal, jadi hook yang perlu melihat setiap hasil memerlukan kedua-duanya.PermissionRequest: apabila panggilan alat memerlukan keputusan kebenaran, iaitu ketika gesaan kelulusan akan dipaparkan.UserPromptSubmit: apabila anda menyerahkan gesaan, sebelum Claude memprosesnya. Output stdout teks biasa daripada hook yang berjaya ditambahkan pada konteks model.SessionStartdanSessionEnd: pada setiap penghujung sesi.SessionStartturut dicetuskan selepas pemadatan, di bawah nilai matchercompact.Stop: apabila Claude selesai memberikan respons. Peristiwa ini berlaku sekali bagi setiap giliran, bukan sekali bagi setiap tugas yang selesai.
Bagi peristiwa yang menyokong matcher, satu kumpulan boleh mengandungi matcher yang menentukan kejadian yang akan menjalankan hook. Bagi peristiwa alat, matcher menapis berdasarkan nama alat. Oleh itu, "Edit|Write" dicetuskan untuk suntingan fail dan tidak untuk kejadian lain. Matcher peka huruf besar-kecil. Matcher kosong dicetuskan bagi setiap kejadian. Alat daripada pelayan MCP (model context protocol) dinamakan mcp__<server>__<tool>. Oleh itu, matcher "mcp__github__.*" menangkap alat daripada satu pelayan dan tidak mempengaruhi alat daripada pelayan lain.
Stop hook mempunyai perangkap yang perlu diketahui sebelum anda menulisnya. Hook Stop yang menyekat akan menghantar model kembali untuk bekerja. Secara lalai, Claude Code akan mengatasi sekatan seterusnya selepas lapan sambungan berturut-turut, dan kiraan itu ditetapkan semula setiap kali Claude memanggil alat. Baca medan stop_hook_active daripada input hook dan keluar dengan kod 0 apabila nilainya benar. Jika tidak, hook anda boleh terus menghantar Claude kembali untuk bekerja.
Data yang diterima oleh hook pada stdin
Apabila Claude hendak menjalankan npm test, hook PreToolUse pada Bash membaca data ini pada stdin:
{
"session_id": "abc123",
"cwd": "/home/deploy/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}Medan input biasa termasuk session_id, cwd, transcript_path dan hook_event_name; permission_mode tidak dihantar pada setiap peristiwa. Peristiwa alat menambah tool_name, tool_input dan tool_use_id. Peristiwa lain membawa medan tersendiri: UserPromptSubmit menerima teks prompt, dan SessionStart menerima source yang mengandungi startup, resume, clear, compact atau fork.
jq ialah cara biasa untuk membaca data ini di dalam skrip shell, dan imej pelayan minimum tidak menyertakannya. Pasang ia terlebih dahulu dengan sudo apt install -y jq pada Ubuntu dan Debian.
Kesan status keluar terhadap panggilan alat yang sedang berjalan
Terdapat tiga hasil.
- Exit 0 bermaksud kejayaan, dan sebarang medan keputusan JSON yang sah masih terpakai, termasuk sekatan atau penolakan. Pada
PreToolUse, exit 0 tanpa keputusan tidak bermakna kelulusan, dan aliran kebenaran biasa masih berjalan. PadaUserPromptSubmit,UserPromptExpansion,SessionStartdanPostModelSwitch, stdout teks biasa ditambah ke dalam konteks model. Pada kebanyakan peristiwa lain, stdout hanya dihantar ke log nyahpepijat (debug log). - Exit 2 menyekat tindakan pada peristiwa yang boleh disekat, termasuk
PreToolUse, dan stderr menjadi mesej yang disertakan bersama sekatan tersebut melainkan output JSON mengandungi keputusan sekatan, yang mana alasannya akan diutamakan. Pihak yang membaca mesej tersebut bergantung pada peristiwa itu. PadaPreToolUsedanStop, model melihatnya sebagai alasan. PadaUserPromptSubmitdanPreModelSwitch, ia dipaparkan kepada anda dan tidak ditambah ke dalam konteks model. PadaPostToolUsedanPostToolUseFailure, yang tidak boleh disekat, sekatan diabaikan, walaupun stderr masih sampai kepada model sebagai maklum balas. Pada kebanyakan peristiwa lain yang tidak boleh disekat, stderr hanya dipaparkan kepada anda atau diabaikan. PadaStop,SubagentStop,TaskCompleteddan hookUserPromptSubmitsesuatu pemalam, exit 2 dengan stdout kosong dan ralat fail-hilang pada stderr dianggap sebagai ralat yang tidak menyekat. - Sebarang kod keluar lain dengan stdout teks biasa atau kosong biasanya merupakan ralat yang tidak menyekat. Transkrip menunjukkan notis ralat hook yang membawa baris pertama stderr selepas teks
Failed with non-blocking status code:. JSON yang sah masih boleh menentukan hasil pada peristiwa sepertiPreToolUse, melainkan kegagalan hook tersebut menyekat tindakan.WorktreeCreategagal pada sebarang exit bukan sifar, danWorktreeRemovegagal pada exit bukan sifar jika direktori masih wujud selepas itu.
Untuk sebarang perkara selain menyekat atau berdiam diri, gunakan exit 0 dan cetak objek JSON ke stdout sebaliknya. Hook PreToolUse membuat keputusan dengan permissionDecision:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}"allow" melangkau gesaan interaktif di mana peraturan kebenaran dan keperluan kelulusan alat membenarkannya, "deny" membatalkan panggilan dan menghantar alasan kepada model, dan "ask" meminta pengesahan. Pilih satu gaya bagi setiap hook. Mencampurkan exit 2 dengan keputusan JSON pada stdout akan mengekalkan sekatan, walaupun JSON menyatakan "allow".
Apabila beberapa hook sepadan dengan satu peristiwa, ia berjalan secara selari, dengan hook gesaan dan ejen dihadkan kepada dua belas yang berjalan serentak. deny daripada satu hook tidak menghentikan hook lain yang berkaitan, jadi hook pengelogan masih menulis barisnya sementara hook kawalan (guardrail) menolak panggilan yang sama. Bagi PreToolUse, Claude Code kemudian menggabungkan jawapan dan mengekalkan yang paling ketat, mengikut urutan: tolak, tangguh, tanya, benarkan.
Contoh 1: menyekat arahan yang merosakkan sebelum ia dijalankan
Simpan ini sebagai .claude/hooks/block-destructive.sh dalam projek 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 0Jadikannya boleh laksana, kemudian daftarkannya pada PreToolUse dalam .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 skrip tersebut secara manual sebelum anda mempercayainya, kerana hook yang terhenti akibat inputnya sendiri biasanya akan gagal dalam keadaan terbuka (fail open) apabila onFailure tidak ditetapkan. Pada Windows tanpa Git Bash, hook arahan PreToolUse atau PermissionRequest dalam bentuk shell yang gagal boleh sebaliknya menyekat panggilan alat tersebut:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?Anda sepatutnya melihat baris Blocked by policy: pada stderr dan kod keluar (exit code) sebanyak 2. Masukkan arahan yang tidak berbahaya seperti ls -la dan anda sepatutnya tidak melihat sebarang output serta kod keluar sebanyak 0. Dalam satu sesi, panggilan yang dinafikan akan muncul dalam transkrip dengan mesej anda sebagai sebabnya, dan model akan membaca mesej tersebut serta menyesuaikan diri.
Satu sifat menjadikan langkah ini berbaloi: hook PreToolUse tercetus sebelum semakan mod kebenaran, dalam setiap mod kebenaran, jadi penafian tetap berkuat kuasa walaupun di bawah bypassPermissions. Itulah yang menjadikan hook berguna di samping mod automatik Claude Code dan tetapan kebenarannya, di mana gesaan (prompts) dikurangkan tetapi hook masih tetap tercetus.
Bersikap jujurlah tentang perkara ini. Pemadanan corak pada rentetan arahan ialah penghadang (guardrail) terhadap ejen yang cuai, dan ia bukanlah sempadan terhadap ejen yang bijak, kerana arahan yang sama boleh ditulis dalam bentuk yang tidak pernah dilihat oleh grep anda. Peraturan tegas sepatutnya berada dalam sistem kebenaran dan dalam akaun tempat proses tersebut dijalankan.
Contoh 2: format dan lint selepas setiap suntingan
PostToolUse dengan pemadan Edit|Write akan berjalan selepas salah satu daripada alat penyuntingan fail tersebut berjaya. Simpan 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 menambah fungsi dengan indentasi yang salah ke dalam fail Python, kemudian buka fail tersebut. Fail itu akan kembali dalam keadaan terformat. Itu adalah bukti bahawa hook telah berjalan, kerana hook yang berjaya tidak akan memaparkan apa-apa dalam perbualan.
exit 2 di sini tidak membatalkan apa-apa. PostToolUse dicetuskan selepas alat tersebut selesai dilaksanakan, jadi suntingan itu tetap berada pada cakera walau apa pun. Apa yang anda peroleh daripada exit 2 ialah output ruff check sampai kepada model sebagai maklum balas, supaya ia membetulkan ralat yang baru sahaja diperkenalkan dan bukannya meneruskan kerja. Itulah perbezaan antara kegagalan lint yang anda temui semasa waktu commit dengan kegagalan yang dibaiki oleh ejen dalam pusingan yang sama.
Dua had pemadan penting di sini. Edit|Write tidak melihat fail yang diubah oleh arahan shell, dan Claude menulis fail melalui Bash dengan cukup kerap sehingga jurang itu menjadi nyata. Untuk liputan setiap panggilan, padankan Bash juga dan minta skrip menyenaraikan fail yang diubah dengan git status --porcelain. Untuk liputan sekali setiap pusingan, letakkan imbasan dalam hook Stop sebaliknya.
Contoh 3: log setiap panggilan alat untuk audit
Matcher kosong pada PostToolUse dicetuskan bagi setiap panggilan alat yang berjaya kecuali EndConversation. Menghantar rekod ke system journal dan bukannya ke fail dalam direktori home tidak menjadikannya di luar capaian shell milik agent itu sendiri: capaian bergantung pada permission akaun. Pengguna boleh membaca journal peribadi masing-masing, manakala root dan ahli systemd-journal, adm atau wheel boleh membaca semua fail journal:
{
"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 semula rekod itu dengan journalctl -t claude-code -o cat | tail -n 5. Jika mempunyai permission untuk membaca rekod, anda sepatutnya melihat satu baris JSON bagi setiap panggilan alat yang berjaya selain EndConversation, dengan rekod terbaharu pada baris terakhir. Jika tiada apa-apa dipaparkan, semak capaian journal dan sama ada hook telah dijalankan; bahagian penyelesaian masalah di bawah menerangkan hook tersebut.
Tambahkan blok yang sama di bawah PostToolUseFailure untuk merekod panggilan yang gagal, kerana PostToolUse hanya dicetuskan apabila panggilan berjaya dan arahan yang gagal biasanya lebih penting. Sebab menggunakan logger dan bukannya menambah rekod pada fail dalam direktori home ialah pemilikan: hook berjalan sebagai pengguna yang sama dengan shell agent, jadi apa-apa yang boleh ditambah oleh pengguna itu juga boleh dipadamkan kandungannya. Journal ditulis oleh systemd-journald; perlindungannya daripada pemadaman masih bergantung pada keistimewaan akaun agent.
Tempoh maksimum hook boleh berjalan
Data di sebalik carta 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
}
]Secara lalai, command hook mempunyai masa 600 saat, iaitu sepuluh minit. Sesetengah peristiwa mengurangkan tempoh ini dengan ketara. Semua hook SessionEnd berkongsi peruntukan masa sebanyak 1.5 saat, jadi pembersihan pada akhir sesi mesti dilakukan dengan cepat. Namun, menetapkan timeout yang lebih panjang pada sesuatu hook dalam fail tetapan akan meningkatkan peruntukan masa bersama itu kepada nilai yang sepadan, sehingga 60 saat.
Command, HTTP atau MCP tool hook segerak yang mencapai had masa akan dibatalkan dan biasanya tidak menghasilkan keputusan. Pada PreModelSwitch, tamat masa akan menyekat pertukaran. Untuk PreToolUse guardrail, tamat masa biasanya membenarkan panggilan tool diteruskan ke aliran kebenaran biasa, dengan pengecualian Windows di atas apabila onFailure tidak ditetapkan. Oleh itu, pastikan skrip guardrail ringkas. Mulai release 2.1.295, anda boleh membalikkan tingkah laku lalai itu pada hook command atau http dengan "onFailure": "block". Tetapan ini menjadikan tamat masa, crash atau exit code yang tidak dijangka sebagai sekatan. Namun, tetapan ini tidak berkuat kuasa pada Stop, SubagentStop, TaskCompleted, TeammateIdle atau command hook latar belakang. Untuk kerja perlahan yang tidak perlu ditunggu oleh sesiapa, seperti menghantar log ke lokasi lain, tetapkan "async": true supaya hook berjalan di latar belakang tanpa melambatkan panggilan tool.
Cangkuk, fail peraturan, kemahiran dan pelayan MCP
Empat perkara ini sering dikelirukan kerana semuanya mengubah tindakan ejen. Hanya satu daripadanya tidak lagi sekadar cadangan.
Fail peraturan (CLAUDE.md atau fail di bawah .claude/rules/) ialah teks yang dimuatkan ke dalam konteks model. Fail ini membentuk tingkah laku, tetapi tidak menguatkuasakan apa-apa. Dalam perbualan yang panjang, diff yang besar dan permintaan pengguna yang baharu, satu baris daripadanya boleh terlepas daripada perhatian. Inilah mekanisme biasa yang menyebabkan ejen mengabaikan arahan yang anda tulis.
Kemahiran ialah folder yang mengandungi arahan dan skrip. Model memuatkannya apabila menganggap kemahiran itu berkaitan. Pertimbangan tersebut ialah tujuan kemahiran, dan juga hadnya: model masih membuat keputusan. Anda boleh melihat kedua-dua aspek ini dalam kemahiran seperti Ponytail, yang mengarahkan ejen supaya membuat perubahan paling kecil yang berfungsi, kerana kemahiran itu membentuk pendekatan terhadap keseluruhan tugasan dengan cara yang tidak dapat dilakukan oleh cangkuk, dan hanya apabila model memilih untuk memuatkannya.
Pelayan MCP (protokol konteks model) memberikan model alat baharu untuk dipanggil. Pelayan ini memperluas perkara yang boleh dicapai oleh ejen. Namun, pelayan ini tidak menyebabkan ejen menggunakan mana-mana alat, dan ia merupakan proses berasingan yang perlu anda kendalikan. Pengendalian itu sendiri ialah tugas khusus: lihat menjalankan pelayan MCP pada VPS.
Cangkuk ialah satu-satunya daripada empat perkara ini yang berjalan tanpa dipilih oleh model. Gunakan fail peraturan untuk menetapkan keutamaan, dan gunakan kemahiran untuk prosedur yang perlu diikuti oleh model apabila berkaitan. Gunakan cangkuk untuk langkah yang mesti berlaku setiap kali, atau untuk perkara yang tidak boleh berlaku sama sekali. Perbandingan yang lebih terperinci, termasuk keadaan kemahiran lebih sesuai daripada fail peraturan, terdapat dalam perbandingan kemahiran, MCP dan fail peraturan.
Plugin ialah kaedah pembungkusan, bukan mekanisme kelima. Plugin menggabungkan cangkuk dengan kemahiran menjadi satu unit yang boleh dipasang. Dengan cara ini, pasukan boleh menggunakan kawalan yang sama pada setiap mesin: lihat cara plugin Claude Code berfungsi.
Keputusan keselamatan pada VPS kongsi
Hook ialah kod yang dicetuskan oleh ejen, dan ia berjalan sebagai pengguna yang memulakan Claude Code. Ia mewarisi keizinan fail dan persekitaran pengguna tersebut. Pada komputer riba, ini adalah persoalan aliran kerja. Pada VPS di mana ejen berjalan tanpa pengawasan, ia adalah persoalan keselamatan dengan empat bahagian praktikal.
Hook dalam repositori ialah kod yang bukan anda tulis. .claude/settings.json dikomitkan, jadi mengklon repositori dan memulakan sesi di dalamnya boleh mendaftarkan hook yang disertakan bersama repositori tersebut. Dalam sesi interaktif, Claude Code menyekat hook projek di sebalik dialog kepercayaan ruang kerja untuk folder tersebut, yang bermaksud menerima kepercayaan adalah saat anda memutuskan untuk menjalankannya. Baca blok hooks terlebih dahulu. Sesi claude -p atau SDK, iaitu cara ejen tanpa pengawasan biasanya berjalan, tidak akan memaparkan dialog tersebut dan menganggap folder itu sebagai dipercayai, jadi hook repositori akan berjalan tanpa bertanya. Semak fail .claude/ sebelum anda menulis skrip untuknya, atau jalankan dengan --settings '{"disableAllHooks": true}'.
Hook melihat input alat sepenuhnya. Hook audit yang merekodkan tool_input menulis setiap argumen bagi setiap perintah ke dalam log, termasuk mana-mana token yang kebetulan berada pada baris perintah. Log tersebut kemudiannya memerlukan perlindungan yang sama seperti rahsia itu sendiri, yang merupakan sebahagian daripada masalah yang lebih luas iaitu menjauhkan rahsia daripada capaian ejen AI.
Hook boleh menulis ke dalam konteks model. stdout teks biasa daripada hook SessionStart atau UserPromptSubmit yang berjaya akan ditambah ke dalam perbualan. Hook yang menyalurkan teks dari luar, penjejak isu atau fail log, sebenarnya menyerahkan teks yang tidak dipercayai kepada model seolah-olah anda sendiri yang menaipnya. Hook yang memajukan nota daripada sesi Claude Code lain pada VPS yang sama melakukan perkara yang sama, dan output satu ejen tidak mempunyai tuntutan kepercayaan yang lebih tinggi daripada penjejak isu. Anggap stdout tersebut sebagai input dan bukannya sebagai output.
Keistimewaan ialah kawalan sebenar. Jalankan ejen sebagai pengguna khusus tanpa keistimewaan dengan hanya peraturan sudo yang diperlukan. Penafian PreToolUse adalah berbaloi untuk dimiliki, dan ia direka sebagai usaha terbaik: rujukan menyatakan perkara yang sama tentang penapis if dan memberitahu anda untuk menggunakan sistem keizinan apabila anda memerlukan penafian keras. Peraturan keizinan dan akaun yang menjalankan proses tersebut adalah bahagian yang bertahan di bawah tekanan.
Satu sifat tetap kekal dalam setiap mod keizinan. Hook PreToolUse dicetuskan sebelum semakan mod keizinan dalam setiap mod keizinan, jadi hook yang mengembalikan deny akan menyekat alat walaupun di bawah bypassPermissions. Hook boleh memperketat apa yang dibenarkan oleh peraturan keizinan. Ia tidak boleh melonggarkannya. Pengecualiannya ialah mod. Pada mesin tanpa tetapan terurus dan tanpa fail managed-mcp.json, dalam sesi yang tidak dilog masuk melalui /login ke pelan Pasukan atau Perusahaan, mod yang dipasang yang mengendalikan tool.check boleh meluluskan panggilan yang disekat oleh hook PreToolUse anda. Dengan tetapan terurus, fail managed-mcp.json, atau /login Pasukan atau Perusahaan sebagai kelayakan sesi, panggilan yang disekat oleh hook PreToolUse akan kekal disekat secara lalai, tidak kira dari fail tetapan mana hook itu datang. Sesi yang berjalan pada kunci API atau CLAUDE_CODE_OAUTH_TOKEN jangka panjang, iaitu cara banyak pelayan menjalankannya, dikira sebagai tidak dilog masuk walaupun log masuk disimpan. Semak perkara yang boleh diubah oleh mod Claude Code sebelum anda memasangnya pada pelayan.
Mengapa hook saya tidak berfungsi?
Selesaikan langkah ini mengikut urutan. Setiap langkah menyatakan simptom yang akan anda lihat.
- Jalankan
/hooksdan pastikan hook tersebut muncul di bawah acara yang anda jangkakan. Hook yang tiada dalam menu biasanya bermaksud fail tetapan mempunyai ralat sintaks JSON, memandangkan koma di hujung dan komen tidak dibenarkan, atau fail tersebut tidak berada di salah satu daripada enam lokasi di atas. - Bandingkan pemadan (matcher) dengan nama alat dengan tepat. Pemadan adalah sensitif kepada huruf besar dan kecil, jadi
"bash"tidak akan memadankan alatBash. - Jalankan skrip secara manual dengan input sampel, seperti dalam contoh 1 di atas. Kod keluar (exit code) yang tidak dijangka adalah pepijat dalam skrip anda; semak juga stdout skrip tersebut, kerana JSON yang sah masih boleh memberikan keputusan pada acara seperti
PreToolUse. - Notis yang memaparkan
jq: command not foundbermaksudjqtiada pada mesin tersebut.command not founduntuk skrip anda sendiri bermaksud laluan tidak dapat diselesaikan, jadi gunakan${CLAUDE_PROJECT_DIR}atau laluan mutlak (absolute path). Jika skrip tidak berjalan langsung, kemungkinan besar ia tidak boleh dilaksanakan (executable). - Hook mencetak JSON yang sah tetapi tiada apa-apa berlaku. Pada macOS dan Linux, hook berbentuk shell berjalan melalui
sh -cdalam shell bukan interaktif, tetapi sesetengah persediaan masih memuatkan profil anda, sepertiBASH_ENVyang menghala ke~/.bashrc. Jika profil tersebut mencetak sepanduk (banner), sepanduk itu akan diletakkan di hadapan JSON anda. Stdout tidak lagi bermula dengan{, jadi Claude Code membaca keseluruhan kandungan sebagai teks biasa dan mengabaikan keputusan tersebut. Oleh kerana hook keluar dengan kod 0, transkrip tidak menunjukkan sebarang ralat. Pada kebanyakan acara, teks tersebut hanya pergi ke log nyahpepijat (debug log), manakala padaUserPromptSubmit,UserPromptExpansion,SessionStartdanPostModelSwitch, ia ditambah ke dalam konteks model, termasuk sepanduk tersebut. Balut sebarangechodalam profil anda supaya ia hanya berjalan dalam shell interaktif. - Masih buntu: mulakan sesi dengan
claude --debug-file /tmp/claude.logdan jalankantail -f /tmp/claude.logdalam terminal kedua. Log nyahpepijat merekodkan hook mana yang sepadan, kod keluar yang dikembalikan oleh setiap hook, serta semua yang ditulis ke stdout dan stderr.
FAQ
Apakah perbezaan antara hook Claude Code dan arahan CLAUDE.md?
Arahan CLAUDE.md ialah teks dalam konteks model, jadi ia bersaing untuk mendapatkan perhatian dengan perbualan dan permintaan semasa, dan model boleh menimbang arahan tersebut berbanding perkara lain. Hook ialah arahan shell yang dijalankan oleh Claude Code pada titik tetap dalam kitaran hayatnya, jadi ia dilaksanakan pada setiap kejadian peristiwa tersebut tanpa mengira keputusan model. Gunakan arahan untuk keutamaan. Gunakan hook untuk langkah yang mesti sentiasa berlaku atau tindakan yang tidak boleh berlaku sama sekali.
Bagaimanakah cara untuk menghalang Claude Code daripada menjalankan arahan shell tertentu?
Daftarkan hook PreToolUse dengan pemadan Bash yang membaca arahan daripada .tool_input.command, menulis sebab ke stderr dan keluar dengan kod 2. Claude Code membatalkan panggilan tersebut dan menunjukkan sebab anda kepada model, dan ini berlaku sebelum semakan mod kebenaran, jadi penolakan tersebut kekal walaupun dalam mod bypassPermissions. Pemadanan corak pada rentetan arahan adalah sebagai pengadang (guardrail) dan bukannya sempadan keselamatan, kerana arahan yang sama boleh ditulis dalam bentuk yang terlepas daripada corak tersebut, jadi sokong ia dengan peraturan kebenaran dan akaun tanpa keistimewaan (unprivileged).
Hook saya mencetak JSON yang sah tetapi tiada apa-apa berlaku. Mengapa?
Semak profil shell anda untuk teks yang dicetak sebelum JSON. Pada macOS dan Linux, hook tanpa medan args dijalankan melalui sh -c, dan dalam persediaan yang masih memuatkan profil anda, seperti BASH_ENV yang menghala ke ~/.bashrc, profil yang mencetak sepanduk akan meletakkannya pada stdout sebelum JSON anda. Oleh kerana output tidak lagi bermula dengan {, Claude Code menganggap kesemuanya sebagai teks biasa dan mengabaikan keputusan tersebut, dan kerana hook keluar dengan kod 0, transkrip tidak menunjukkan ralat. Lindungi sebarang echo dalam profil anda dengan ujian shell interaktif, kemudian sahkan pembetulan dengan membaca log nyahpepijat daripada claude --debug-file /tmp/claude.log.
Adakah selamat untuk menjalankan hook Claude Code pada pelayan kongsi?
Hook dijalankan sebagai pengguna yang memulakan Claude Code, dengan kebenaran fail pengguna tersebut, jadi hook boleh melakukan apa sahaja yang boleh dilakukan oleh akaun itu. Dua tabiat merangkumi kebanyakan risiko: jalankan ejen sebagai akaun tanpa keistimewaan khusus dengan polisi sudo yang terhad, dan baca blok hooks bagi mana-mana repositori sebelum anda menerima dialog kepercayaan ruang kerja atau menjalankan claude -p di dalamnya, kerana hook projek dihantar di dalam .claude/settings.json dan mod -p tidak pernah menunjukkan dialog tersebut. Tetapkan "disableAllHooks": true dalam fail tetapan anda untuk melumpuhkan hook, kecuali untuk hook terurus yang memerlukan tetapan tersebut pada peringkat terurus; tetapan projek false boleh mengatasi tetapan pengguna true.