SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

Claude Code Hook Yapısı ve Çalışma Mantığı

Claude Code hook mekanizmasının çalışma prensiplerini, tetiklenen olayları ve exit code 2 durumunun araç çağrılarını nasıl iptal ettiğini teknik detaylarıyla inceleyin.

Claude Code hook nedir

Claude Code hook'ları, Claude Code'un kendi yaşam döngüsü içindeki belirli noktalarda otomatik olarak çalıştırdığı kabuk komutlarıdır. Hook ile kural dosyası arasındaki temel fark budur. CLAUDE.md içindeki bir yönerge tavsiye niteliğindedir ve model bunu bağlamındaki diğer her şeyle birlikte değerlendirir. Hook ise koddur; model kabul etse de etmese de çalışır. Eğer ajanınız iki kez belirttiğiniz biçimlendiriciyi atlamaya devam ediyorsa, daha sert bir yönergeye değil, bir hook'a ihtiyacınız vardır.

Mekanizma oldukça basittir. Bir ayar dosyasında bir olay adı altında bir komut tanımlarsınız. O olay tetiklendiğinde, Claude Code komutunuzu çalıştırır ve olay verilerini standart girdi (stdin) üzerinden JSON (JavaScript object notation) formatında yazar. Komutunuz bu veriyi okur, işlemini yapar ve bir çıkış durumu ile yanıt verir. Bir PreToolUse hook'undan dönen 2 çıkış kodu, araç çağrısını çalışmadan iptal eder. Komut dosyanızın standart hata (stderr) çıktısına yazdığı her şey, hook engelleme kararı içeren bir JSON yazdırmadığı sürece modelin reddedilme nedeni olarak geri döndürülür; engelleme kararı içeren JSON'ın nedeni önceliklidir.

Buradaki olay adları ve alan adları, 12 Kasım 2026 tarihinde kontrol edilen Claude Code hooks referansı kaynaklıdır. Bu yapı hızla değişebildiği için, herhangi bir blog yazısından (buna dahil) JSON kopyalamadan önce kendi sürümünüz için referansı kontrol edin. Kendi yapılandırmanızı claude --version ile yazdırabilirsiniz.

Hook yapılandırmasının konumu

Hook, bir ayar dosyasındaki JSON bloğudur. Bir hook altı farklı konumda bulunabilir ve dosyanın kapsamı, hook'un kapsamını belirler.

  • ~/.claude/settings.json: makinenizdeki her proje için geçerlidir, diğer kullanıcıları etkilemez.
  • .claude/settings.json: tek bir proje için geçerlidir, depoya commit edilir; böylece depoyu klonlayan herkes hook'u alır.
  • .claude/settings.local.json: tek bir proje için geçerlidir, yalnızca sizin makinenizde çalışır.
  • Yönetilen politika ayarları: kurum genelinde geçerlidir, bir yönetici tarafından belirlenir.
  • hooks/hooks.json bir eklenti içinde yer alır, eklenti etkin olduğu sürece çalışır.
  • Skill veya subagent ön bilgisi (frontmatter). Bir skill çağrıldığında, o skill'e ait hook'lar oturumun geri kalanında aktif kalır; bir subagent'ın hook'ları ise subagent çalıştığı sürece aktiftir.

Bu dosyalardaki hook girdileri birbirinin üzerine yazmak yerine birleştirilir. Bir proje ayar dosyası, kendi hook'larını kullanıcı ayarlarınızdaki hook'lara ekler; bu sayede tek bir olay, farklı dosyalardan gelen birden fazla hook'u tetikleyebilir. "disableAllHooks": true ayarı, yönetilen politika ayarlarından gelen hook'lar hariç olmak üzere tüm hook'ları devre dışı bırakır; yönetilen politika ayarlarındaki hook'lar, bu ayar yönetilen ayarlarda da uygulanmadığı sürece çalışmaya devam eder.

Oturum içerisinde kayıtlı tüm hook'ları listelemek için /hooks komutunu çalıştırın. Bu komut, hook'ları olaya göre gruplandırır ve her biri için kaynak dosya ile eşleştiriciyi gösterir. Menü salt okunurdur; bu nedenle bir hook'u değiştirmek için ilgili ayar dosyasını düzenlemeniz gerekir. Dosya izleyici (file watcher), yapılan değişiklikleri genellikle yeniden başlatmaya gerek kalmadan algılar.

Hangi Claude Code kanca olayları mevcuttur

Kanca referansı, sıkıştırma, alt aracılar, çalışma ağaçları ve yapılandırma dosyalarını kapsayan SessionStart ile SessionEnd arasında otuz üç olay listeler. Sunucu çalışmaları bunların bir kısmını kullanır.

  • PreToolUse: EndConversation hariç, bir araç çağrısı yürütülmeden önce. Engelleyebilen tek kanca budur.
  • PostToolUse: EndConversation hariç, bir araç çağrısı başarıyla tamamlandıktan sonra. Başarısızlık durumunda bunun yerine PostToolUseFailure tetiklenir; bu nedenle her sonucu görmesi gereken bir kancanın her ikisine de ihtiyacı vardır.
  • PermissionRequest: Bir araç çağrısı izin kararı gerektirdiğinde, yani onay isteminin görüneceği an.
  • UserPromptSubmit: Bir istem gönderdiğinizde, Claude onu işlemeden önce. Başarılı bir kancadan gelen düz metin stdout, modelin bağlamına eklenir.
  • SessionStart ve SessionEnd: Bir oturumun her iki ucunda. SessionStart ayrıca compact eşleştirici değeri altında sıkıştırmadan sonra tetiklenir.
  • Stop: Claude yanıt vermeyi bitirdiğinde. Bu, tamamlanmış bir görev için değil, her tur için bir kez gerçekleşir.

Eşleştiricileri destekleyen olaylarda, bir grup, kancanın hangi durumlarda çalışacağına karar veren bir matcher taşıyabilir. Araç olaylarında bu, araç adına göre filtreleme yapar; bu nedenle "Edit|Write" yalnızca dosya düzenlemelerinde tetiklenir ve başka hiçbir şeyde çalışmaz. Eşleştiriciler büyük/küçük harfe duyarlıdır. Boş bir eşleştirici her durumda tetiklenir. Bir MCP (model context protocol) sunucusundan gelen araçlar mcp__<server>__<tool> olarak adlandırılır; bu nedenle "mcp__github__.*" eşleştiricisi, bir sunucunun araçlarını yakalar ve diğerlerini olduğu gibi bırakır.

Stop kancaları, yazmadan önce bilinmesi gereken bir tuzağa sahiptir. Engelleyici bir Stop kancası, modeli tekrar çalışmaya gönderir ve varsayılan olarak Claude Code, sekiz ardışık devam işleminden sonra bir sonraki bloğu geçersiz kılar; sayaç, Claude bir araç çağırdığında sıfırlanır. Kanca girişinden stop_hook_active alanını okuyun ve doğru olduğunda 0 ile çıkış yapın; aksi takdirde kancanız Claude'u sürekli çalışmaya geri göndermeye devam edebilir.

Bir kancanın stdin üzerinde aldığı veriler

Claude npm test işlemini çalıştırmak üzereyken, Bash üzerindeki bir PreToolUse kancası stdin üzerinde şu verileri okur:

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

Yaygın girdi alanları arasında session_id, cwd, transcript_path ve hook_event_name bulunur; permission_mode her olayda gönderilmez. Araç olayları tool_name, tool_input ve tool_use_id alanlarını ekler. Diğer olaylar kendi alanlarını taşır: UserPromptSubmit, prompt metnini alır ve SessionStart; startup, resume, clear, compact veya fork değerlerinden oluşan bir source alır.

jq, bir shell betiği içerisinde bu veriyi okumanın olağan yoludur ve minimal bir sunucu imajında bu araç bulunmayabilir. Öncelikle Ubuntu ve Debian üzerinde sudo apt install -y jq ile kurulumunu yapın.

Çıkış durumunun devam eden araç çağrısı üzerindeki etkisi

Üç olası sonuç vardır.

  • Çıkış 0, başarı anlamına gelir ve engelleme veya reddetme dahil olmak üzere geçerli tüm JSON karar alanları geçerliliğini korur. PreToolUse üzerinde, bir karar içermeyen çıkış 0 onay anlamına gelmez ve normal izin akışı çalışmaya devam eder. UserPromptSubmit, UserPromptExpansion, SessionStart ve PostModelSwitch üzerinde, düz metin stdout modelin bağlamına eklenir. Diğer çoğu olayda stdout yalnızca hata ayıklama günlüğüne gider.
  • Çıkış 2, PreToolUse dahil olmak üzere engellenebilir olaylarda işlemi engeller ve JSON çıktısı engelleme kararı içermediği sürece stderr, engelleme ile birlikte gelen mesaj haline gelir; JSON kararının nedeni önceliklidir. Bu mesajı kimin okuyacağı olaya bağlıdır. PreToolUse ve Stop üzerinde model bunu neden olarak görür. UserPromptSubmit ve PreModelSwitch üzerinde mesaj size gösterilir ve modelin bağlamına eklenmez. Engellenemeyen PostToolUse ve PostToolUseFailure üzerinde engelleme yoksayılır, ancak stderr geri bildirim olarak modele ulaşmaya devam eder. Engellenemeyen diğer çoğu olayda stderr yalnızca size gösterilir veya yoksayılır. Stop, SubagentStop, TaskCompleted ve bir eklentinin UserPromptSubmit kancasında, boş stdout ve stderr üzerinde dosya bulunamadı hatası ile gelen çıkış 2, engelleme yapmayan bir hata olarak değerlendirilir.
  • Diğer tüm çıkış kodları, düz metin veya boş stdout ile birlikte genellikle engelleme yapmayan bir hatadır. Transkript, Failed with non-blocking status code: metninden sonra stderr'in ilk satırını içeren bir kanca hata bildirimi gösterir. Kancanın başarısızlığı işlemi engellemediği sürece, PreToolUse gibi olaylarda geçerli JSON sonucu belirleyebilir. WorktreeCreate sıfır olmayan her çıkışta başarısız olur; WorktreeRemove ise işlem sonrasında dizin hala mevcutsa sıfır olmayan çıkışta başarısız olur.

Engelleme veya sessiz kalma dışındaki durumlar için çıkış 0 kullanın ve stdout'a bir JSON nesnesi yazdırın. Bir PreToolUse kancası permissionDecision ile karar verir:

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

"allow", izin kurallarının ve aracın onay gereksinimlerinin izin verdiği durumlarda etkileşimli istemi atlar; "deny" çağrıyı iptal eder ve nedeni modele gönderir; "ask" ise onay ister. Her kanca için bir stil seçin. Çıkış 2 ile stdout üzerindeki bir JSON kararını karıştırmak, JSON "allow" dese bile engellemeyi aktif tutar.

Birden fazla kanca aynı olayla eşleştiğinde bunlar paralel çalışır; istem ve aracı kancaları aynı anda en fazla on iki adet çalışacak şekilde sınırlandırılmıştır. Bir kancadan gelen deny, kardeş kancaları durdurmaz; bu nedenle bir güvenlik kancası aynı çağrıyı reddederken bir günlükleme kancası kendi satırını yazmaya devam eder. PreToolUse için Claude Code yanıtları birleştirir ve reddetme, erteleme, sorma, izin verme sırasına göre en kısıtlayıcı olanı tutar.

Örnek 1: yıkıcı bir komutu çalışmadan önce engelleme

Bunu projenizde .claude/hooks/block-destructive.sh olarak kaydedin:

#!/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

Çalıştırılabilir hale getirin ve ardından .claude/settings.json içindeki PreToolUse üzerinde kaydedin:

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"
          }
        ]
      }
    ]
  }
}

Komut dosyasını güvenilir bulmadan önce manuel olarak test edin; çünkü kendi girdisinde çöken bir kanca, onFailure ayarlanmadığında genellikle açık kalır (fail open). Git Bash olmayan Windows sistemlerinde, başarısız olan bir shell-form PreToolUse veya PermissionRequest komut kancası, araç çağrısını engelleyebilir:

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

stderr üzerinde Blocked by policy: satırını ve 2 çıkış kodunu görmelisiniz. ls -la gibi zararsız bir komut gönderdiğinizde herhangi bir çıktı görmemeli ve 0 çıkış kodunu almalısınız. Bir oturumda, reddedilen çağrı transkriptte neden olarak mesajınızla birlikte görünür; model bu mesajı okur ve uyum sağlar.

Bir özellik, bunu yapmaya değer kılar: PreToolUse kancaları, izin modu denetiminden önce ve her izin modunda tetiklenir; bu nedenle bir engelleme, bypassPermissions altında bile geçerliliğini korur. Kancayı, istemlerin kısıldığı ancak kancanın hala tetiklendiği Claude Code otomatik modu ve izin ayarları ile birlikte kullanışlı kılan şey budur.

Bunun ne olduğu konusunda dürüst olun. Bir komut dizisi üzerinde desen eşleştirme (pattern matching), bir ajanın dikkatsizliğine karşı bir güvenlik önlemidir; ajanın zekice davranmasına karşı bir sınır değildir, çünkü aynı komut grep aracınızın asla görmeyeceği bir biçimde yazılabilir. Kesin kurallar, izin sistemine ve sürecin altında çalıştığı hesaba aittir.

Örnek 2: her düzenlemeden sonra biçimlendirme ve lint işlemi

PostToolUse ve Edit|Write eşleştiricisi, bu dosya düzenleme araçlarından herhangi biri başarıyla tamamlandığında çalışır. Bunu .claude/hooks/after-edit.sh olarak kaydedin:

#!/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
          }
        ]
      }
    ]
  }
}

Claude'dan bir Python dosyasına kötü girintilenmiş bir fonksiyon eklemesini isteyin ve ardından dosyayı açın. Dosya biçimlendirilmiş olarak geri dönecektir. Bu, kancanın (hook) çalıştığının kanıtıdır; çünkü başarılı bir kanca işlemi konuşma içerisinde herhangi bir çıktı göstermez.

Buradaki exit 2 komutu hiçbir işlemi geri almaz. PostToolUse, araç zaten çalıştırıldıktan sonra tetiklendiği için düzenleme her halükarda diske yazılmıştır. exit 2 kullanmanın sağladığı avantaj, ruff check çıktısının modele geri bildirim olarak ulaşmasıdır; böylece model bir sonraki adıma geçmek yerine az önce oluşturduğu hatayı düzeltir. Commit aşamasında fark ettiğiniz bir lint hatası ile ajanın aynı tur içerisinde onardığı bir hata arasındaki fark budur.

Burada iki eşleştirici sınırı önemlidir. Edit|Write, bir shell komutu tarafından değiştirilen dosyaları görmez ve Claude dosyaları genellikle Bash aracılığıyla yazdığı için bu boşluk gerçek bir sorundur. Çağrı bazında kapsama sağlamak için Bash ile de eşleştirme yapın ve betiğin değiştirilen dosyaları git status --porcelain ile listelemesini sağlayın. Tur başına kapsama için tarama işlemini bir Stop kancasına yerleştirin.

Örnek 3: Denetim için her araç çağrısını günlüğe kaydetme

PostToolUse üzerindeki boş bir eşleştirici, EndConversation hariç her başarılı araç çağrısında tetiklenir. Kaydı ev dizinindeki bir dosyaya değil de sistem günlüğüne göndermek, kaydı aracın kendi kabuğunun erişiminden korumaz: erişim, hesabın izinlerine bağlıdır. Kullanıcılar kendi özel kullanıcı günlüklerini okuyabilir; root ve systemd-journal, adm veya wheel üyeleri ise tüm günlük dosyalarını okuyabilir:

{
  "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"
          }
        ]
      }
    ]
  }
}

journalctl -t claude-code -o cat | tail -n 5 ile geri okuyun. Kayıtları okuma izniniz varsa, EndConversation dışındaki her başarılı araç çağrısı için en yenisi en altta olacak şekilde bir JSON satırı görmelisiniz. Hiçbir şey görünmüyorsa, günlük erişimini ve kancanın çalışıp çalışmadığını kontrol edin; aşağıdaki sorun giderme bölümü kancayı ele almaktadır.

Başarısız olan çağrıları yakalamak için aynı bloğu PostToolUseFailure altına ekleyin, çünkü PostToolUse yalnızca başarı durumunda tetiklenir ve başarısız bir komut genellikle daha önemli olandır. Ev dizininizdeki bir dosyaya ekleme yapmak yerine logger kullanılmasının nedeni sahiplik durumudur: bir kanca, aracın kabuğuyla aynı kullanıcı olarak çalışır; bu nedenle kullanıcının ekleme yapabildiği her şeyi, aynı kullanıcı silebilir veya içeriğini boşaltabilir. Günlük, systemd-journald tarafından yazılır; günlüğü silinmekten korumak yine de araç hesabının ayrıcalıklarına bağlıdır.

Bir kancanın çalışma süresi

GrafikDefault hook timeout in seconds, by hook type and event
Bu grafiğin arkasındaki veriler
[
  {
    "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
  }
]

Bir komut kancası varsayılan olarak 600 saniye, yani on dakika süre alır. Bazı olaylar bu süreyi ciddi oranda kısıtlar. SessionEnd kancaları, tamamı için 1.5 saniyelik ortak bir bütçeyi paylaşır; bu nedenle oturum sonu temizlik işlemleri hızlı olmalıdır. Ancak ayar dosyalarınızdaki bir kanca üzerinde daha uzun bir timeout değeri belirlemek, bu ortak bütçeyi 60 saniyeye kadar yükseltir.

Zaman aşımına uğrayan eşzamanlı bir komut, HTTP veya MCP aracı kancası iptal edilir ve normal şartlarda herhangi bir karar üretmez; PreModelSwitch üzerinde ise zaman aşımı geçişi engeller. Bir PreToolUse güvenlik bariyeri için zaman aşımı, normalde araç çağrısının standart izin akışına devam etmesine izin verir; ancak onFailure ayarlanmadığında yukarıda belirtilen Windows istisnası geçerlidir. Bu nedenle güvenlik bariyeri betiklerini kısa tutun. 2.1.295 sürümünden itibaren, "onFailure": "block" kullanarak bir command veya http kancasındaki bu varsayılan davranışı tersine çevirebilirsiniz. Bu işlem; zaman aşımını, çökmeyi veya beklenmedik bir çıkış kodunu engelleme durumuna dönüştürür. Ancak bu ayarın Stop, SubagentStop, TaskCompleted, TeammateIdle veya arka plan komut kancaları üzerinde bir etkisi yoktur. Bir günlüğü başka bir yere göndermek gibi kimsenin beklemediği yavaş işlemler için "async": true ayarını yapın; böylece kanca, araç çağrısını bekletmeden arka planda çalışır.

Kancalar, kural dosyaları, yetenekler ve MCP sunucuları

Dört farklı kavram, ajanın davranışını değiştirdikleri için birbirine karıştırılmaktadır. Bunlardan sadece biri öneri olmaktan çıkar.

Bir kural dosyası (CLAUDE.md veya .claude/rules/ altındaki bir dosya), modelin bağlamına yüklenen metindir. Davranışı şekillendirir ancak hiçbir şeyi zorunlu kılmaz. Uzun bir konuşma, büyük bir diff ve yeni bir kullanıcı isteği karşısında, kural dosyasındaki tek bir satır etkisini yitirebilir. Ajanların yazdığınız talimatları görmezden gelmesinin arkasındaki olağan mekanizma budur.

Yetenek (skill), modelin ilgili olduğunu düşündüğünde yüklediği talimatlar ve betikler klasörüdür. Bu değerlendirme yeteneğin temelidir, ancak aynı zamanda sınırıdır: kararı yine model verir. Ajani çalışan en küçük değişikliğe yönlendiren Ponytail gibi bir yetenekte her iki tarafı da görebilirsiniz; çünkü bu, hiçbir kancanın yapamayacağı şekilde tüm göreve yaklaşım biçimini şekillendirir ve bunu yalnızca model onu yüklemeyi seçtiği sürece yapar.

Bir MCP (model context protocol) sunucusu, modele çağırabileceği yeni araçlar sağlar. Ajanın erişebileceği alanı genişletir. Ajanı bir şeye erişmeye zorlamaz ve yönetmeniz gereken ayrı bir süreçtir; bu başlı başına bir iştir: bir VPS üzerinde MCP sunucuları çalıştırma konusuna bakınız.

Kanca (hook), bu dördü arasında modelin seçimi olmadan çalışan tek mekanizmadır. Bir tercih için kural dosyasını, modelin uygularken izlemesi gereken bir prosedür için yeteneği kullanın. Her zaman gerçekleşmesi gereken bir adım veya asla gerçekleşmemesi gereken bir durum için kancayı kullanın. Bir yeteneğin kural dosyasından ne zaman daha üstün olduğu dahil olmak üzere daha derinlemesine karşılaştırma için yetenekler, MCP ve kural dosyaları karşılaştırması bölümüne bakınız.

Eklenti (plugin), beşinci bir mekanizma değil, bir paketleme biçimidir. Kancaları yeteneklerle birlikte tek bir kurulabilir birimde toplar; bir ekibin aynı güvenlik sınırını her makineye nasıl dağıttığı budur: Claude Code eklentilerinin çalışma mantığı konusuna bakınız.

Paylaşımlı bir VPS üzerinde güvenlik kararı

Hook, ajanın tetiklediği ve Claude Code'u başlatan kullanıcı yetkileriyle çalışan koddur. Bu kullanıcının dosya izinlerini ve ortam değişkenlerini devralır. Bir dizüstü bilgisayarda bu bir iş akışı sorusudur. Ajanın gözetimsiz çalıştığı bir VPS'de ise dört pratik boyutu olan bir güvenlik meselesidir.

Bir depodaki hook, sizin yazmadığınız koddur. .claude/settings.json commit edildiği için, bir depoyu klonlamak ve içinde bir oturum başlatmak, depo ile birlikte gelen hook'ların kaydedilmesine neden olabilir. Etkileşimli bir oturumda Claude Code, proje hook'larını o klasör için çalışma alanı güven (workspace trust) diyaloğu arkasında tutar; yani güveni kabul etmek, onları çalıştırmaya karar verdiğiniz andır. Önce hooks bloğunu okuyun. Gözetimsiz bir ajanın genellikle çalışma şekli olan bir claude -p veya SDK oturumu, bu diyaloğu asla göstermez ve klasörü güvenilir kabul eder; bu nedenle deponun hook'ları sormadan çalışır. Bir hook'a karşı betik yazmadan önce .claude/ dosyalarını inceleyin veya --settings '{"disableAllHooks": true}' ile çalıştırın.

Bir hook, tam araç girdisini görür. tool_input kaydı tutan bir denetim hook'u, komut satırında yer alan herhangi bir token dahil olmak üzere her komutun tüm argümanlarını bir günlüğe yazar. Bu günlük, gizli verinin kendisiyle aynı korumaya ihtiyaç duyar; bu da gizli verileri AI ajanının erişiminden uzak tutma konusundaki daha geniş sorunun bir parçasıdır.

Bir hook, modelin bağlamına yazabilir. Başarılı bir SessionStart veya UserPromptSubmit hook'undan gelen düz metin stdout, konuşmaya eklenir. Dışarıdan, bir sorun takip sisteminden veya bir günlük dosyasından metin aktaran bir hook, sanki siz yazmışsınız gibi güvenilmeyen metni modele sunar. Aynı VPS üzerindeki başka bir Claude Code oturumundan not ileten bir hook da aynı şeyi yapar ve bir ajanın çıktısı, sorun takip sisteminin çıktısından daha fazla güveninizi hak etmez. Bu stdout'u çıktı olarak değil, girdi olarak değerlendirin.

Asıl kontrol yetkilerdedir. Ajanı, yalnızca ihtiyaç duyduğu sudo kurallarına sahip, yetkisiz ve özel bir kullanıcı olarak çalıştırın. Bir PreToolUse reddi (deny) kullanışlıdır ancak tasarımı gereği "en iyi çaba" (best effort) prensibiyle çalışır: referans, if filtresi için de aynısını söyler ve kesin bir engelleme gerektiğinde izin sistemini kullanmanızı önerir. İzin kuralları ve sürecin altında çalıştığı hesap, baskı altında ayakta kalan kısımlardır.

Her izin modunda geçerli olan bir özellik vardır. PreToolUse hook'ları, her izin modunda izin denetiminden önce tetiklenir; bu nedenle deny dönen bir hook, bypassPermissions altında bile aracı engeller. Hook'lar izin kurallarının izin verdiğini kısıtlayabilir. Ancak genişletemezler. İstisna bir mod'dur. Yönetilen ayarları ve managed-mcp.json dosyası olmayan bir makinede, Team veya Enterprise planına /login üzerinden giriş yapılmamış bir oturumda, tool.check işleyen yüklü bir mod, PreToolUse hook'unuzun engellediği bir çağrıyı onaylayabilir. Yönetilen ayarlar, bir managed-mcp.json dosyası veya oturum kimlik bilgisi olarak bir Team veya Enterprise /login'si ile, bir PreToolUse hook'unun engellediği bir çağrı, hook hangi ayar dosyasından gelirse gelsin varsayılan olarak engelli kalır. Bir API anahtarı veya uzun ömürlü bir CLAUDE_CODE_OAUTH_TOKEN üzerinde çalışan oturum (birçok sunucunun çalışma şekli budur), giriş yapılmış olsa bile giriş yapılmamış sayılır. Bir sunucuya yüklemeden önce Claude Code modlarının neleri değiştirebileceğini kontrol edin.

Kancam neden tetiklenmiyor?

Bu adımları sırasıyla uygulayın. Her adım, karşılaşacağınız belirtiyi tanımlar.

  • /hooks komutunu çalıştırın ve kancanın beklediğiniz etkinlik altında görünüp görünmediğini kontrol edin. Menüde görünmeyen bir kanca, genellikle ayar dosyasında bir JSON sözdizimi hatası olduğu anlamına gelir; çünkü sondaki virgüllere ve yorum satırlarına izin verilmez veya dosya yukarıda belirtilen altı konumdan birinde değildir.
  • Eşleştiriciyi (matcher), araç adıyla tam olarak karşılaştırın. Eşleştiriciler büyük/küçük harfe duyarlıdır, bu nedenle "bash" ifadesi Bash aracını asla eşleştirmez.
  • Yukarıdaki 1. örnekte olduğu gibi, betiği örnek girdiyle manuel olarak çalıştırın. Beklemediğiniz bir çıkış kodu, betiğinizdeki bir hatadır; stdout çıktısını da kontrol edin, çünkü geçerli JSON verisi PreToolUse gibi etkinliklerde yine de bir karar döndürebilir.
  • jq: command not found uyarısı, ilgili makinede jq aracının eksik olduğu anlamına gelir. Kendi betiğiniz için alınan bir command not found hatası, yolun çözümlenemediğini gösterir; bu durumda ${CLAUDE_PROJECT_DIR} komutunu veya mutlak bir dosya yolu kullanın. Betik hiçbir şekilde çalışmıyorsa, muhtemelen çalıştırılabilir (executable) iznine sahip değildir.
  • Kanca geçerli JSON çıktısı veriyor ancak hiçbir şey olmuyor. macOS ve Linux üzerinde, shell formundaki bir kanca, etkileşimli olmayan bir kabukta sh -c aracılığıyla çalıştırılır; ancak bazı kurulumlar, ~/.bashrc dosyasını işaret eden BASH_ENV gibi profillerinizi kaynak olarak kullanmaya devam eder. Eğer bu profil bir karşılama mesajı (banner) yazdırıyorsa, bu mesaj JSON çıktınızın başına eklenir. Stdout artık { ile başlamadığı için Claude Code çıktının tamamını düz metin olarak okur ve kararı yok sayar. Kanca 0 koduyla çıktığı için transkriptte herhangi bir hata görünmez. Çoğu etkinlikte bu metin yalnızca hata ayıklama günlüğüne (debug log) giderken, UserPromptSubmit, UserPromptExpansion, SessionStart ve PostModelSwitch etkinliklerinde banner dahil olmak üzere modelin bağlamına eklenir. Profilinizdeki tüm echo komutlarını, yalnızca etkileşimli kabuklarda çalışacak şekilde sarmalayın.
  • Hâlâ sorun yaşıyorsanız: oturumu claude --debug-file /tmp/claude.log ile başlatın ve ikinci bir terminalde tail -f /tmp/claude.log komutunu çalıştırın. Hata ayıklama günlüğü, hangi kancaların eşleştiğini, her birinin hangi çıkış kodunu döndürdüğünü ve stdout ile stderr'e yazdıkları her şeyi kaydeder.

FAQ

Claude Code hook ile CLAUDE.md talimatı arasındaki fark nedir?

CLAUDE.md talimatı, modelin bağlamındaki bir metindir; bu nedenle konuşma ve mevcut istek ile dikkat çekmek için yarışır ve model bunu diğerleriyle kıyaslayabilir. Hook ise Claude Code'un yaşam döngüsünde sabit bir noktada çalıştırdığı bir shell komutudur; dolayısıyla modelin kararı ne olursa olsun, ilgili olay her gerçekleştiğinde çalışır. Tercihleriniz için talimatları, her zaman gerçekleşmesi gereken bir adım veya asla gerçekleşmemesi gereken bir eylem için ise hook kullanın.

Claude Code'un belirli bir shell komutunu çalıştırmasını nasıl engellerim?

PreToolUse hook'unu, komutu .tool_input.command üzerinden okuyan, stderr'e bir neden yazan ve 2 koduyla çıkan bir Bash eşleştiricisi ile kaydedin. Claude Code çağrıyı iptal eder ve modelinize nedeninizi gösterir. Bu işlem izin modu denetiminden önce gerçekleştiği için, engelleme bypassPermissions modunda dahi geçerli kalır. Bir komut dizisi üzerinde desen eşleştirme (pattern matching) bir güvenlik sınırı değil, bir koruma katmanıdır; aynı komut, desenin gözden kaçırabileceği bir biçimde yazılabilir. Bu nedenle, bu yöntemi izin kuralları ve yetkisiz bir hesap ile destekleyin.

Hook'um geçerli JSON çıktısı veriyor ancak hiçbir şey olmuyor. Neden?

Shell profilinizde JSON'dan önce yazdırılan metinleri kontrol edin. macOS ve Linux üzerinde, args alanı olmayan bir hook sh -c üzerinden çalışır. ~/.bashrc dosyasını işaret eden BASH_ENV gibi profilinizi kaynaklayan (source) kurulumlarda, bir banner yazdıran profil, bu çıktıyı JSON'ınızdan önce stdout'a yerleştirir. Çıktı artık { ile başlamadığı için Claude Code tüm içeriği düz metin olarak ele alır ve kararı görmezden gelir. Hook 0 koduyla çıktığı için de transkriptte herhangi bir hata görünmez. Profilinizdeki tüm echo komutlarını etkileşimli shell testi ile korumaya alın, ardından claude --debug-file /tmp/claude.log üzerinden hata ayıklama günlüğünü okuyarak düzeltmeyi doğrulayın.

Paylaşımlı bir sunucuda Claude Code hook'larını çalıştırmak güvenli midir?

Hook'lar, Claude Code'u başlatan kullanıcı olarak ve o kullanıcının dosya izinleriyle çalışır; bu nedenle bir hook, ilgili hesabın yapabildiği her şeyi yapabilir. İki alışkanlık riskin çoğunu kapsar: ajanı kısıtlı bir sudo politikasına sahip, yetkisiz bir hesapla çalıştırın ve herhangi bir deponun çalışma alanı güven diyalogunu kabul etmeden veya içinde claude -p çalıştırmadan önce hooks bloğunu okuyun. Proje hook'ları .claude/settings.json içinde gelir ve -p modu bu diyalogu asla göstermez. Hook'ları devre dışı bırakmak için ayar dosyanızda "disableAllHooks": true değerini ayarlayın; ancak yönetilen düzeyde ayar gerektiren yönetilen hook'lar bu durumun istisnasıdır. false şeklindeki bir proje ayarı, true şeklindeki bir kullanıcı ayarını geçersiz kılabilir.

Bu yazı işinize yaradı mı?