Claude · Gelişmiş · 202 Genişlet · Konu 4 / 5
4.4 Hooks
"Genelde uyar" yetmiyorsa kuralı hook'a yaz.
Bu sayfada ne öğreneceksin
- Hook'un ne olduğunu ve CLAUDE.md'den farkını: hook zorlar, CLAUDE.md bağlam verir
- Olay adlarını, ayar dosyasının şemasını ve exit kodlarının ne yaptığını
- Hook'un senin yetkinle çalışan bir kabuk komutu olduğunu ve neye dikkat edeceğini
Kısaca
CLAUDE.md'ye "her düzenlemeden sonra biçimlendiriciyi çalıştır" yazabilirsin. Çoğu zaman uyar, bazen uymaz. Kurs bunu şöyle koyuyor: CLAUDE.md bir istektir, garanti değildir; gözetlemediğin uzun bir çalışmada "genelde" yetmez. Hook ise belirleyici (deterministic) koddur: döngünün sabit bir noktasında çalışır, böylece kuralı "Claude genelde dinler" olmaktan "Claude atlayamaz" yapar.
Dokümana göre hook'lar kullanıcı tanımlı kabuk komutlarıdır. Claude Code bunları yaşam döngüsünün belirli noktalarında çalıştırır; belirli işlerin, modelin çalıştırmayı seçmesine bağlı kalmadan her seferinde olmasını sağlar. Aynı sayfada hook'un başka türleri de var (HTTP, istem tabanlı, ajan tabanlı); bu sayfada yalnızca kabuk komutu ("type": "command") hook'larını işliyoruz.
Bu özellik kabuk komutu çalıştırır. Doküman açık uyarıyor: komut hook'ları tam kullanıcı yetkinle çalışır; kullanıcı hesabının erişebildiği her dosyayı değiştirebilir, silebilir ya da okuyabilir. Eklemeden önce her hook komutunu oku ve dene. Ayrıntısı "Güvenlik" bölümünde.
Ne işe yarar
Kurs ve doküman şu kullanımları sayıyor:
- Dosya düzenlendikten sonra otomatik biçimlendirme
- Uyumluluk için çalıştırılan her komutun kaydı
- Tehlikeli işlemleri engelleme, örneğin üretim dosyalarını değiştirmeyi
- Claude bir işi bitirince ya da senden girdi beklerken bildirim gönderme
- Bağlam sıkıştırıldıktan sonra önemli bilgiyi yeniden bağlama koyma
Olay adları
Hook'u bir olaya bağlarsın. Olay adı ayar dosyasında anahtar olarak aynen yazılır. En sık kullanılanlar (dokümandaki tabloya göre):
| Olay | Ne zaman çalışır |
|---|---|
SessionStart | Oturum başlarken ya da devam ederken |
UserPromptSubmit | Bir istem gönderildiğinde, Claude işlemeden önce |
PreToolUse | Bir araç çağrısı çalışmadan önce; engelleyebilir |
PermissionRequest | Bir araç çağrısı izin kararı gerektirdiğinde |
PostToolUse | Bir araç çağrısı başarılı olduktan sonra |
PostToolUseFailure | Bir araç çağrısı başarısız olduktan sonra |
Notification | Claude Code bildirim gönderdiğinde |
SubagentStart, SubagentStop | Bir subagent başlatıldığında, bittiğinde |
Stop | Claude cevabını bitirdiğinde |
InstructionsLoaded | Bir CLAUDE.md ya da .claude/rules/*.md dosyası bağlama yüklendiğinde |
PreCompact, PostCompact | Bağlam sıkıştırılmadan önce, sıkıştırma bittikten sonra |
SessionEnd | Oturum bittiğinde |
Başka olaylar da var (ConfigChange, CwdChanged, FileChanged, WorktreeCreate ve diğerleri). Tam liste dokümanın Hooks reference sayfasında; kursun dediği gibi hepsini bilmen gerekmez, küçük bir kısmını tekrar tekrar kullanırsın. Bazı olayların ayrıntısı:
PreToolUsekursa göre "zorlama aracı"dır: bir şey olmadan önce onu durdurabilen olaydır.PostToolUsearaç zaten çalıştıktan sonra tetiklenir; eylemi geri alamaz. Otomatik biçimlendirme ve lint buraya gider.StopClaude bitirmek istediğinde çalışır; bir koşul sağlanmadıysa "henüz bitmedin" diyebilirsin.- Sıkıştırma sonrası bağlama bilgi koymak için
PostCompactdeğil,SessionStartolayınıcompacteşleştiricisiyle kullan. Kurs, çıktısı konuşmaya gerçekten geri dönen olayın bu olduğunu söylüyor.
Ayar dosyası şeması
Hook'lar JSON ayar dosyalarında tanımlanır. Dokümana göre üç iç içe seviye vardır: önce bir olay seçersin, sonra ne zaman tetikleneceğini daraltan bir eşleştirici grubu (matcher group) eklersin, sonra çalışacak bir ya da daha fazla hook işleyicisi (handler) tanımlarsın. Dokümandaki bildirim örneği şu biçimdedir:
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Bu örnek macOS içindir (osascript). Linux ve Windows komutları için dokümanın hooks-guide sayfasında "Get notified when Claude needs input" bölümüne bak. Ayar dosyasında zaten bir hooks anahtarı varsa yeni olayı onun kardeşi olarak ekle, tümünü değiştirme: her olay adı tek bir hooks nesnesinin içinde bir anahtardır.
Eşleştirici (matcher). Eşleştirici olmazsa hook olayın her oluşunda çalışır. Araç olaylarında (PreToolUse, PostToolUse vb.) eşleştirici araç adına bakar: Bash yalnızca Bash aracını yakalar, Edit|Write ikisinden birini yakalar. Eşleştirici büyük küçük harfe duyarlıdır. SessionStart için eşleştirici oturumun nasıl başladığına bakar (startup, resume, clear, compact, fork). Her olay farklı bir alana bakar; ayrıntı referans sayfasında.
İşleyici alanları. Her işleyicide type zorunludur ("command" kabuk komutu çalıştırır) ve komut hook'unda command zorunludur. İsteğe bağlı alanlardan bazıları: if (hook'u yalnızca belirli bir araç çağrısında çalıştırmak için, örneğin "Bash(git *)"), timeout (saniye), statusMessage. Dokümana göre if filtresi en iyi çabayla çalışır; kesin bir izin ya da yasak uygulamak için hook yerine izin sistemini kullan.
Dosya nerede durur. Hook'un nerede tanımlandığı kapsamını belirler:
| Konum | Kapsam | Paylaşılır mı |
|---|---|---|
~/.claude/settings.json | Tüm projelerin | Hayır, makinene özel |
.claude/settings.json | Tek proje | Evet, repoya commit edilebilir |
.claude/settings.local.json | Tek proje | Hayır |
| Yönetilen politika ayarları | Kurum genelinde | Evet, yönetici kontrolünde |
Plugin hooks/hooks.json | Plugin açıkken | Evet, plugin ile gelir |
| Skill ya da subagent frontmatter'ı | Skill çağrıldıktan sonra oturum boyunca; subagent çalışırken | Evet, dosyada tanımlı |
Kurs, .claude/settings.json'daki hook'ların proje düzeyinde olduğunu ve repoya konabildiğini, böylece ekibin hepsinin aynı hook'ları aldığını söylüyor. Komutlarda projedeki betiklere CLAUDE_PROJECT_DIR ortam değişkeniyle başvur; Claude'un çalışma klasörü ne olursa olsun çalışır. Tanımladıklarını görmek için oturumda /hooks yaz. Kurs bunun salt okunur bir liste açtığını söylüyor; hook'u düzenlemek için ayar dosyasını düzenlersin.
Exit kodları: engelleyen hangisi
Hook'a olayın verisi stdin'den JSON olarak gelir. Örneğin Bash komutunu çalıştırmadan önce PreToolUse hook'u tool_name ve tool_input (Bash için içindeki command) alanlarını görür. Hook sonucu exit kodu ve çıktısıyla bildirir:
| Exit kodu | Ne olur |
|---|---|
| 0 | Başarı; eylem sürer. PreToolUse'ta 0, çağrıyı onaylamak anlamına gelmez; çağrı yine normal izin akışından geçer |
| 2 | Engelleme hatası. Engellenebilen olaylarda Claude Code eylemi durdurur. stderr'e yazdığın mesaj gerekçe olur; olaya göre Claude'a geri bildirim olarak gider, böylece neden engellendiğini bilir ve yön değiştirir |
| Diğer her kod | Engellemeyen hata. Eylem sürer; çoğu olayda transcript'te bir "hook error" bildirimi görürsün |
En çok yanılınan nokta: exit 1 engellemez. Unix'te hata kodu olarak bilinir ama hook'ta eylem yine çalışır. Doküman uyarıyor: hook bir politikayı uygulamak içinse exit 2 kullan. (Dokümanda onFailure alanı gibi, hook başarısız olunca eylemi durduran bir ayar da var; ayrıntı için referans sayfasına bak.)
Exit 2'nin etkisi olaya bağlıdır, çünkü bazı olaylar zaten olmuş şeyleri temsil eder. Dokümandaki tablodan örnekler:
| Olay | Engelleyebilir mi | Exit 2 ne yapar |
|---|---|---|
PreToolUse | Evet | Araç çağrısını engeller |
UserPromptSubmit | Evet | İstemi engeller, Claude'a hiç ulaşmaz |
Stop | Evet | Claude'un durmasını engeller, konuşma sürer |
PreCompact | Evet | Sıkıştırmayı engeller |
PostToolUse | Hayır | stderr'i Claude'a gösterir; araç zaten çalıştı |
Notification | Hayır | Exit kodu ve stderr yok sayılır |
SessionStart | Hayır | stderr yalnızca sana gösterilir |
Basit hook'lar exit koduyla yetinir. Daha ayrıntılı kontrol için hook exit 0 ile stdout'a bir JSON nesnesi yazar. Örneğin PreToolUse bir çağrıyı reddedip nedenini söyleyebilir:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Use rg instead of grep for better performance"
}
}
permissionDecision değerleri: "allow" (izin istemini atla), "deny" (çağrıyı iptal et ve gerekçeyi Claude'a ver), "ask" (kullanıcıya normal izin istemini göster). Bir dördüncü değer "defer" yalnızca etkileşimsiz -p modunda var. Dokümana göre exit 2 ile JSON'u birlikte kullanma, hook başına birini seç: karıştırırsan exit 2 engeli korur; JSON alanları okunur ama engeli kaldıramaz ("allow" bile geçirmez). Bir çağrıyı engellemek yerine yeniden yazmak için updatedInput alanı var (örneğin komuttan bir sırrı silip çalıştırmak için). Kurs bir uyarı veriyor: updatedInput tüm girdi nesnesinin yerine geçer, değiştirmediğin alanları da geri yazmalısın, yoksa kaybolurlar.
Doküman ayrıca şunu belirtiyor: bir hook'un "deny" kararı her izin modunda geçerlidir, bypassPermissions modunda ve --dangerously-skip-permissions ile bile. Bu, kullanıcıların izin modunu değiştirerek aşamayacağı bir politika uygulamanı sağlar.
Hook ile CLAUDE.md farkı
| CLAUDE.md | Hook | |
|---|---|---|
| Ne | Bağlam; Claude'a rehberlik | Belirleyici kod; Claude'dan bağımsız çalışır |
| Uyum | Genelde uyulur, garanti yok | Olay olunca her seferinde çalışır |
| Engelleyebilir mi | Hayır | Evet (PreToolUse gibi olaylarda, exit 2 ile) |
| Ne için | Proje bilgisi, komutlar, tercihler | "Asla şunu yapma" ve "her zaman şunu yap" kuralları |
Kural: kritik bir kural varsa CLAUDE.md'ye yaz, ama yetmez; engellenmesi gereken eylemi bir PreToolUse hook'una koy. Önceki sayfadaki skill için de aynı: skill'deki bir kural her seferinde uygulanmalıysa dokümanın önerisi onu hook'a taşımak, hook'u skill'in hooks alanında da tanımlayabilirsin.
Güvenlik
- Hook bir kabuk komutudur ve senin yetkinle çalışır. Dokümanın uyarısı: komut hook'ları tam kullanıcı izinleriyle çalışır, hesabının erişebildiği her dosyayı değiştirebilir, silebilir, okuyabilir. Başkasından aldığın bir hook'u okumadan ekleme, kendi yazdığını da önce dene.
- Başkasının deposundaki hook'a dikkat. Dokümana göre etkileşimli oturumda Claude Code, bir klasörün çalışma alanı güven iletişim kutusunu (workspace trust dialog) kabul edene kadar hiçbir ayar dosyasındaki hook'u çalıştırmaz. Ancak
-pya da SDK oturumunda iletişim kutusu hiç gösterilmez ve klasör güvenilir sayılır; bu yüzden güvenmediğin bir deponun.claude/settings.jsondosyasındaki hook'lar çalışır. Yazmadığın bir depodaclaude -pkullanmadan önce.claude/ayar dosyalarını oku. - Betik yazarken: doküman şu pratikleri öneriyor: girdileri doğrula ve temizle, kabuk değişkenlerini her zaman tırnakla (
"$VAR"),..ile yol atlamayı engelle, betikler için mutlak yol kullan,.env,.git/ve anahtar gibi hassas dosyalardan uzak dur. - Yanlış yapılandırma sessiz kalabilir. Dokümana göre betik yolu yanlışsa ya da dosya çalıştırılabilir değilse hook başlamaz ve bu, engellemeyen bir hatadır: eylem yine gerçekleşir. Bir politika hook'unu ilk çalıştırdığında hata bildirimini izle.
- Hook'a sır koyma.
.claude/settings.jsonrepoya girer. Anahtar, parola, jeton yazma.
Adım adım
- Kuralı seç. "Asla" ya da "her zaman" diyebildiğin ve CLAUDE.md'de duran ama tutmayan bir kural bul. Bu sayfadaki örnek kurgusaldır:
rmile başlayan komutları engelle. - Olayı ve eşleştiriciyi seç. Çalışmadan önce durdurmak için
PreToolUse, Bash aracı için eşleştiriciBash. - Betiği yaz. Betik stdin'den JSON'u okur, komutu çıkarır, engellemek istiyorsa nedenini stderr'e yazıp
exit 2ile çıkar. Aşağıdaki "Hazır komutlar"da dokümandaki örnek betik var. Betiktejqkullanılıyor; yoksa kurman gerekir. - Çalıştırılabilir yap. macOS ve Linux'ta
chmod +x. Doküman: betik çalıştırılabilir olmazsa Claude Code onu çalıştıramaz. - Ayar dosyasına ekle.
.claude/settings.jsoniçinePreToolUsebloğunu koy. Komutta betik yolunu"$CLAUDE_PROJECT_DIR"ile ver. - Önce betiği elle dene. Örnek JSON'u betiğe boruyla ver ve exit kodunu yazdır. Beklenen sonuç: engel mesajı ve 2. Bu, bir hook hatasında dokümanın da önerdiği ilk kontrol.
/hooksile doğrula. Claude Code oturumunda/hooksyaz; hook'unPreToolUsealtında göründüğünü gör. Görünmüyorsa JSON geçerli mi bak (sondaki virgül ve yorum satırı olmaz), dosya doğru yerde mi bak, gerekirse oturumu yeniden başlat.- Gerçek oturumda dene. Zararsız bir ortamda (boş bir deneme klasörü) Claude'dan kurgusal
deneme.txtdosyasınırmile silmesini iste. Claude Code çağrıyı çalışmadan engellemeli ve betiğin mesajını Claude'a vermeli.
Hazır komutlar
Betik dosyası, .claude/hooks/no-rm.sh olarak kaydet. Bu, dokümandaki örnek betiğin aynısıdır; yalnızca rm ile başlayan komutları yakalar, gerçek bir güvenlik politikası için yetmez:
#!/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
Çalıştırılabilir yap (terminalde, proje klasöründe):
chmod +x .claude/hooks/no-rm.sh
Ayar dosyası, .claude/settings.json (dosya zaten varsa hooks anahtarını mevcut içeriğe ekle):
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/no-rm.sh"
}
]
}
]
}
}
Betiği elle dene (terminalde, proje klasöründe). Beklenen: engel mesajı ve çıkış kodu 2:
echo '{"tool_name":"Bash","tool_input":{"command":"rm deneme.txt"}}' | .claude/hooks/no-rm.sh
echo $?
Hook'un kayıtlı olduğunu görmek için (Claude Code oturumunda):
/hooks
Hazır prompt
Hook'u Claude'a yazdırmak için (dokümana göre Claude'dan hook yazmasını isteyebilirsin; yazdıktan sonra betiği ve ayar dosyasını kendin oku):
Bash aracı çalışmadan önce devreye giren bir PreToolUse hook'u yaz. Komut rm ile başlıyorsa stderr'e nedenini yazıp exit 2 ile çıksın, diğer komutlara karışmasın. Betiği .claude/hooks/no-rm.sh olarak kaydet, ayarı .claude/settings.json dosyasına ekle ve neyi değiştirdiğini bana göster. Dokümana uygun olduğundan emin ol.
Hook çalışıyor mu denemek için (boş bir deneme klasöründe):
deneme.txt adlı kurgusal bir dosyayı rm komutuyla silmeyi dene ve hook'un ne dediğini bana aktar.
Sık yapılan hata
- Engellemek için exit 1 kullanmak. Exit 1 engellemez, eylem yine çalışır. Engellemek için
exit 2. - Hook'u yalnızca CLAUDE.md'ye yazmak. Kuralın garanti olması gerekiyorsa CLAUDE.md yetmez.
- Eşleştiricinin harf duyarlılığını unutmak.
bashdeğilBash. Hook tetiklenmiyorsa/hooksile doğru olay altında göründüğünü ve eşleştiricinin araç adıyla birebir tuttuğunu kontrol et. - Betiği çalıştırılabilir yapmamak ya da
jq'yu kurmamak. "command not found" ya da "jq: command not found" hataları bunlardır. Betik yolu için mutlak yol ya daCLAUDE_PROJECT_DIRkullan. - JSON ve exit 2'yi karıştırmak ya da kabuk profilinin çıktısını JSON'a katmak. Kabuk başlangıç dosyası stdout'a yazı yazıyorsa hook'un JSON'u bozulur. Hook başına tek yöntem seç ve JSON'u
jqgibi bir kodlayıcıyla üret. PostToolUse'tan geri alma beklemek. Araç zaten çalıştı; hook yalnızca geri bildirim verebilir.- Başkasının deposunda hook'lara bakmadan çalışmak. Güvenlik bölümüne bak.
Video
Video: yakında.
Kaynak
- Anthropic Academy, Claude Code 101: Hooks
- Anthropic Academy, Claude Code in Action: Hooks (olaylar,
permissionDecision, exit kodları,updatedInput) - Claude Code dokümanı: Automate actions with hooks (ilk hook, örnekler, konumlar, sorun giderme)
- Claude Code dokümanı: Hooks reference (olay listesi, eşleştirici, işleyici alanları, exit kodu davranışı, güvenlik)
Son doğrulama: 2026-10-21