Claude Code Hooks

Kısaca: Claude Code’un iş akışındaki belirli noktalarda otomatik olarak çalıştırdığı kabuk komutları (veya istemler/ajanlar) – örneğin bir araç çalışmadan önce, Claude cevabını bitirdikten sonra veya bir oturum başlarken ya da biterken.

Biraz daha ayrıntılı: Hook’lar settings.json içinde olay başına (örneğin Stop, PreToolUse, SessionEnd) ve isteğe bağlı olarak bir “eşleştirici” ile (örneğin yalnızca belirli araçlar için) yapılandırılır. Önemli: Stop, tüm konuşmanın sonunda bir kez değil, her cevap turundan sonra tetiklenir – “oturum başına bir kez” için asıl amaçlanan SessionEnd’dir.

Bizim bağlamımız: Bir deneme olarak, her cevaptan sonra tam JSONL dökümünü 1:1 bir Obsidian notuna döken bir Stop hook’u kurduk – ama sonra tekrar bıraktık, çünkü ham metin yerine içerik hakkında yapılandırılmış notlar istemiştiniz. Şimdi bunun gibi sözlük girdilerini konuşma sırasında canlı olarak yazıyorum.

Ayrıntılı

Yapılandırma ve eşleştiriciler

Hook’lar settings.json içinde (veya yerel, işlenmemiş geçersiz kılmalar için settings.local.json içinde) olay başına yapılandırılır. Tipik bir tanım şöyle görünür:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo 'Bash is being run' >> log.txt" }]
      }
    ]
  }
}

matcher, hook’un hangi araçlar/olaylar için tetikleneceğini süzer — eşleştirici olmadan o kategorinin her olayında çalışır. Aynı olay için birkaç hook kaydedilebilir; bunlar sonra art arda çalışır.

Kullanılabilir olay türleri

PreToolUse/PostToolUse (her araç yürütmesinden önce ve sonra) ve Stop (her cevap turundan sonra) dışında, diğerlerinin yanı sıra SessionStart/SessionEnd (bir oturumun başında/sonunda bir kez), UserPromptSubmit (kullanıcı bir mesaj gönderdiğinde, Claude onu işlemeden önce) ve PreCompact (bağlam sıkıştırılmadan önce) vardır. Her olay türü stdin üzerinden farklı yapılandırılmış veri alır (örneğin PreToolUse için aracın adı ve girdi parametreleri JSON olarak) — bir hook betiği bu verileri okuyabilir ve buna dayanarak tepki verip vermeyeceğine ve nasıl vereceğine karar verebilir.

Araç çağrılarını engellemek

Bir PreToolUse hook’u bir araç yürütmesini engelleyebilir bile (belirli bir çıkış kodu veya belirli bir çıktıyla yanıt vererek); bu, örneğin kendi güvenlik kuralları için kullanılabilir — diyelim ki Claude’un kendi muhakemesinden bağımsız olarak belirli Bash komutlarını tümüyle yasaklamak için. Bu, CLAUDE.md içindeki salt talimatlardan önemli bir farktır: hook, akıllıca istem ifadeleriyle aşılamayan, doğrudan çatının (harness) uyguladığı sert bir kuraldır; metin talimatları ise ilke olarak her zaman modelin uyduğu davranış yönergeleridir.

Kabuk komutları ve istemler/ajanlar

Düz kabuk komutlarının yanı sıra hook’lar, tek satırlık betikler değil, daha karmaşık istemleri veya özel ajanları da tetikleyebilir. Bu, örneğin her cevaptan sonra en son değişen dosyalara otomatik olarak bir inceleme ajanı salan bir Stop hook’una veya oturumun özetini üreten bir SessionEnd hook’una olanak tanır — düz bir kabuk betiğinden çok daha güçlüdür, ama başka bir LLM çağrısı söz konusu olduğundan kaynak kullanımı da buna uygun olarak daha yüksektir.

Kulağa benzer gelen olaylar arasındaki önemli farklar

Stop, tüm konuşmanın sonunda bir kez değil, her cevap turundan sonra tetiklenir — asıl istediğiniz “oturum başına bir kez” ise kolayca gözden kaçan bir tuzaktır. Bu amaç için SessionEnd vardır; gerçekten yalnızca tüm oturum bittiğinde tetiklenir. İkisini karıştıran, ya her cevap turunda gereksiz sıklıkta çalışan bir hook’u ya da gerçek sonda istendiği gibi tepki vermeyen bir hook’u göze alır.

Ayrıca bak: JSONL