Anla Dene

Claude · Gelişmiş · 202 Genişlet · Konu 4 / 5

4.4 Hooks

"Genelde uyar" yetmiyorsa kuralı hook'a yaz.

Bu sayfada ne öğreneceksin

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:

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

OlayNe zaman çalışır
SessionStartOturum başlarken ya da devam ederken
UserPromptSubmitBir istem gönderildiğinde, Claude işlemeden önce
PreToolUseBir araç çağrısı çalışmadan önce; engelleyebilir
PermissionRequestBir araç çağrısı izin kararı gerektirdiğinde
PostToolUseBir araç çağrısı başarılı olduktan sonra
PostToolUseFailureBir araç çağrısı başarısız olduktan sonra
NotificationClaude Code bildirim gönderdiğinde
SubagentStart, SubagentStopBir subagent başlatıldığında, bittiğinde
StopClaude cevabını bitirdiğinde
InstructionsLoadedBir CLAUDE.md ya da .claude/rules/*.md dosyası bağlama yüklendiğinde
PreCompact, PostCompactBağlam sıkıştırılmadan önce, sıkıştırma bittikten sonra
SessionEndOturum 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ı:

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:

KonumKapsamPaylaşılır mı
~/.claude/settings.jsonTüm projelerinHayır, makinene özel
.claude/settings.jsonTek projeEvet, repoya commit edilebilir
.claude/settings.local.jsonTek projeHayır
Yönetilen politika ayarlarıKurum genelindeEvet, yönetici kontrolünde
Plugin hooks/hooks.jsonPlugin açıkkenEvet, plugin ile gelir
Skill ya da subagent frontmatter'ıSkill çağrıldıktan sonra oturum boyunca; subagent çalışırkenEvet, 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 koduNe olur
0Başarı; eylem sürer. PreToolUse'ta 0, çağrıyı onaylamak anlamına gelmez; çağrı yine normal izin akışından geçer
2Engelleme 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 kodEngellemeyen 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:

OlayEngelleyebilir miExit 2 ne yapar
PreToolUseEvetAraç çağrısını engeller
UserPromptSubmitEvetİstemi engeller, Claude'a hiç ulaşmaz
StopEvetClaude'un durmasını engeller, konuşma sürer
PreCompactEvetSıkıştırmayı engeller
PostToolUseHayırstderr'i Claude'a gösterir; araç zaten çalıştı
NotificationHayırExit kodu ve stderr yok sayılır
SessionStartHayırstderr 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.mdHook
NeBağlam; Claude'a rehberlikBelirleyici kod; Claude'dan bağımsız çalışır
UyumGenelde uyulur, garanti yokOlay olunca her seferinde çalışır
Engelleyebilir miHayırEvet (PreToolUse gibi olaylarda, exit 2 ile)
Ne içinProje 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

Adım adım

  1. Kuralı seç. "Asla" ya da "her zaman" diyebildiğin ve CLAUDE.md'de duran ama tutmayan bir kural bul. Bu sayfadaki örnek kurgusaldır: rm ile başlayan komutları engelle.
  2. Olayı ve eşleştiriciyi seç. Çalışmadan önce durdurmak için PreToolUse, Bash aracı için eşleştirici Bash.
  3. Betiği yaz. Betik stdin'den JSON'u okur, komutu çıkarır, engellemek istiyorsa nedenini stderr'e yazıp exit 2 ile çıkar. Aşağıdaki "Hazır komutlar"da dokümandaki örnek betik var. Betikte jq kullanılıyor; yoksa kurman gerekir.
  4. Ç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.
  5. Ayar dosyasına ekle. .claude/settings.json içine PreToolUse bloğunu koy. Komutta betik yolunu "$CLAUDE_PROJECT_DIR" ile ver.
  6. Ö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.
  7. /hooks ile doğrula. Claude Code oturumunda /hooks yaz; hook'un PreToolUse altı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.
  8. Gerçek oturumda dene. Zararsız bir ortamda (boş bir deneme klasörü) Claude'dan kurgusal deneme.txt dosyasını rm ile 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

Video

Video: yakında.

Kaynak

Son doğrulama: 2026-10-21

Anla Dene bağımsız bir eğitim sitesidir; Anthropic, OpenAI ya da Google ile bağlantılı değildir. Ürün adları sahiplerine aittir.

anladene.com · Anla Dene Akademi · Gizlilik