Hook Sistemi

Claude bir dosya duzenliyor ve otomatik olarak bir linter calistirmak istiyorsunuz. Claude bir Bash komutu calistiriyor ve bir engelleme listesiyle dogrulamak istiyorsunuz. Claude bir oturum baslatiyoruz ve uyumluluk icin kayit tutmak istiyorsunuz. Hook’lar, Claude’un her eylemini yakalamak, incelemek ve kontrol etmek icin 22 yasam dongusu olayi sunar.

Hook’lar, Claude’un yurutmesi sirasinda belirli noktalarda calisan yasam dongusu geri cagrilaridir — bir arac calismadan once, bir dosya duzenlendikten sonra, bir oturum basladiginda ve 19 baska anda. 22 olay turu ve 4 isleyici turu (command, HTTP, prompt, agent) ile hook’lar CLI’deki en derin genisletilebilirlik noktasidir. Bu bolum, yikici komutlari engelleme ve denetim kaydi tutma gibi guvenlik odakli kaliplar dahil tam yapilandirma referansidir.

Bu Bolumu Nasil Kullanmali

Bu, rehberdeki en uzun bolumdur (866 satir). Dogrusal okumak yerine referans olarak kullanin. Gorsel olarak bir yapilandirma olusturmak icin HookBuilder ile baslayin (satir 800’e atlayin), ardindan ihtiyac duydukca belirli olay tablolarina geri donun. Cogu kullanici toplamda 3-5 hook uygular ve diger 17 olaya hic dokunmaz.

Temel Cikarimlar

• 22 yasam dongusu olayi — SessionStart, PreToolUse, PostToolUse, SubagentStart, ConfigChange ve Claude’un yurutmesindeki her ani kapsayan 17 digeri
• 4 isleyici turu — command (kabuk betikleri), HTTP (politika sunuculari), prompt (AI degerlendirmesi), agent (arac erisimli tam alt ajan)
• Guvenlik koruyuculari — PreToolUse + PostToolUse temeldir: islemleri calismadan once engelle, ardindan her seyi kaydet
• Cikis kodu anlambilimi — 0=izin ver, 2=engelle, diger=gecis birak (Unix kuralinin tersi)
• Eslestiriciler — Kapsami daraltmak icin regex kaliplari: "Bash" kesin eslestirme icin, "Edit|Write" birden fazla arac icin, "mcp__.*" tum MCP araclari icin
• Ortam degiskenleri — CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_ROOT, CLAUDE_ENV_FILE (kalici degiskenler icin yalnizca SessionStart)
• HookBuilder — Etkilesimli gorsel yapilandirma olusturucu (satir 800) — dokumaniere dokunmadan JSON yapilandirmanizi olusturun

Gorsel ogrenen misiniz? HookBuilder’a atlayin (satir 800) ve oncelikle yapilandirmanizi etkilesimli olarak olusturun. Ardindan gercekten ihtiyaciniz olan olay tablolari icin buraya geri donun.

Olay Turleri

Her hook, 22 olaydan birini hedefler. Her olay, Claude’un yasam dongusunde belirli bir anda calisir ve kapsamni daraltmak icin istege bagli olarak bir eslestirici destekler.

Evet, 22 olay cok. Cogu kullanici toplamda 3-5 hook uygular: PreToolUse (guvenlik), PostToolUse (denetim), OnError (kayit), SessionEnd (temizlik), BudgetExceeded (uyarilar). Diger 17 olay ileri duzey is akislari icindir. Hepsini ogrenme zorunlulugu hissetmeyin — belirli bir olaya ihtiyac duydugunuzda asagidaki tablolari referans olarak kullanin.

Isleyici Turleri

Her hook girisi, hook’un nasil calistigini belirleyen dort isleyici turundan birini belirtir.

Command Isleyici

En yaygin isleyici turu. Kabuk komutu, hook baglamini stdin uzerinden JSON olarak alir ve kararini cikis kodlari araciligiyla iletir.

{
  "type": "command",
  "command": "./.claude/hooks/validator.sh",
  "timeout": 600,
  "async": false,
  "statusMessage": "Dogrulaniyor..."
}

• command (gerekli): calistirilacak kabuk komutu
• timeout (istege bagli): iptal oncesi saniye, varsayilan 600
• async (istege bagli): Claude’u engellemeden arka planda calistir
• statusMessage (istege bagli): calisma sirasinda gosterilen dondurucu metni

HTTP Isleyici

JSON girdisini harici bir uc noktaya POST eder. Basliklar $VAR_NAME sozdizimi ile ortam degiskeni interpolasyonunu destekler, ancak yalnizca allowedEnvVars icinde listelenen degiskenler icin.

{
  "type": "http",
  "url": "http://localhost:8080/hooks/validate",
  "headers": {"Authorization": "Bearer $MY_TOKEN"},
  "allowedEnvVars": ["MY_TOKEN"],
  "timeout": 30
}

Prompt Isleyici

Karari bir Claude modeline devreder. Istem metninizdeki $ARGUMENTS yer tutucusu, hook olayindan gelen tam JSON girdisi ile degistirilir.

{
  "type": "prompt",
  "prompt": "Should this bash command run? $ARGUMENTS\n\nDeny commands with 'rm -rf'.",
  "model": "claude-3-5-haiku-20241022",
  "timeout": 30
}

Agent Isleyici

Arac erisimli tam bir alt ajan olusturur. Degerlendirme dosya okuma, komut calistirma veya cok adimli akil yurume gerektirdiginde bunu kullanin.

{
  "type": "agent",
  "prompt": "Verify this operation is safe: $ARGUMENTS",
  "timeout": 60
}

Yapilandirma

Hook’lar settings.json dosyasinda hooks anahtari altinda tanimlanir. Yapi, olay adini, ardindan eslestirici+hook’lar ciftlerinden olusan bir dizi, ardindan her ciftin icindeki isleyici nesnelerinden olusan bir diziyi ic ice geciren bir yapi izler.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/block-rm.sh"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate-edit.sh",
            "timeout": 10,
            "statusMessage": "Duzenleme dogrulaniyor..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/run-linter.sh",
            "timeout": 30,
            "statusMessage": "Linter calistiriliyor..."
          }
        ]
      }
    ]
  }
}

Yapilandirma Kapsamlari

Hook’lar, kisisel varsayilanlardan projeye ozel kurallara kadar birden fazla seviyede tanimlanabilir.

/hooks Tarayicisi

Etkilesimli bir Claude oturumunda, yerlesik hook tarayicisini acmak icin /hooks yazin. Her kapsamdaki kayitli tum hook’lari listeler, hangi olaylari hedeflediklerini gosterir ve yapilandirmanizin dogru yuklendigini dogrulamaniza olanak tanir. Calisma sirasi veya eslestirici sorunlarini giderirken --debug "hooks" ile eslestirin.

Olay Eslestiricileri

Eslestiriciler, bir olayin hangi belirli orneklerinin hook’unuzu tetikleyecegini filtreleyen regex kaliplaridir. Eslestirici olmadan, hook o olay turundeki her olusum icin calisir.

{"matcher": "Bash"}                    // Kesin arac adi
{"matcher": "Edit|Write"}             // Birden fazla arac (regex VEYA)
{"matcher": "mcp__memory__.*"}        // Tum MCP bellek sunucusu araclari
{"matcher": "mcp__.*__write.*"}       // Herhangi bir MCP yazma islemi

Eslestiriciler buyuk/kucuk harf duyarlidir ve tam regex sozdizimi kullanir. Bu, Bash* ifadesinin “Bash ile baslayan her sey” anlamina gelmedigi anlamina gelir — “Bas” ardindan sifir veya daha fazla “h” karakteri anlamina gelir. Kesin arac eslestirmesi icin dogrudan arac adini kullanin: Bash.

Notification olaylari icin eslestirici, bir arac adi yerine bildirim turunu (permission_prompt, idle_prompt) hedefler. SessionStart icin oturum kaynagini (startup, resume, clear, compact) eslestirir.

Cikis Kodu Davranisi

Command isleyicileri, kararlarini cikis kodlari araciligiyla iletir. Bu, hook mekanimalarinin en kritik pareasidir — bu anlambilimi unutursaniz, hook’lariniz islemleri engellemeyi sessizce basaramaz.

# KRITIK: Cikis Kodu Anlambilimi (Unix kuralinin tersi)
exit 0   # IZIN VER -- eylem devam eder
exit 2   # ENGELLE -- eylem onlenir, stderr Claude'a geri beslenir
exit 1   # GECIS BIRAK -- hook hatasi kaydedilir, eylem yine de devam eder

Cikis kodu 2’nin ne engelledigini olaya baglidir:

Ayni olay dizisindeki hook’lar dizi sirasinda sirayla calisir. Cikis kodu 2 ile cikan ilk hook kazanir — dizideki sonraki hook’lar calistirilmaz.

Ortam Degiskenleri

Command hook’lari otomatik olarak birden fazla ortam degiskeni alir:

• CLAUDE_PROJECT_DIR — proje kok dizini
• CLAUDE_PLUGIN_ROOT — plugin kurulum dizini
• CLAUDE_PLUGIN_DATA — plugin kalici veri dizini
• CLAUDE_ENV_FILE — (yalnizca SessionStart) oturum boyunca ortam degiskenlerini saklamak icin dosya yolu

CLAUDE_ENV_FILE degiskeni ozel dikkat hak eder. Bir SessionStart hook’unda, oturumdaki tum sonraki Bash komutlari icin gecerli olacak ortam degiskenleri ayarlamak uzere bu dosyaya export ifadeleri yazabilirsiniz:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Kendi Hook’unuzu Olusturun

Gecerli bir settings.json hook yapilandirmasi olusturmak icin asagidaki etkilesimli olusturucuyu kullanin. Bir olay secin, bir eslestirici ayarlayin, bir isleyici turu secin, detaylari doldurun ve ciktiyi dogrudan projenize kopyalayin.

Guvenlik Koruyuculari Olarak Hook’lar

CI’da --dangerously-skip-permissions kullaniyorsunuz cunku istemleri yanitlayacak bir insan yok. Simdi Claude’un rm -rf / calistirmasini veya ortam degiskenlerinizi harici bir sunucuya curl ile gondermesini hiccbir sey durdurmuyor. Hicbir sey — hook’lar haric. Hook’lar izin atlamasinda hayatta kalan tek guvenlik katmanidir.

Hook’lar yalnizca bir genisletilebilirlik mekanizmasi degildir — Claude CLI’da --dangerously-skip-permissions ile bile atlanamayan tek guvenlik katmanidir. Kabuk betiklerini veya HTTP uc noktalarini arac calistirma yasam dongusune baglamak suretiyla, her oturuma, her kullaniciya ve her ajana uygulanan sert guvenlik sinirlari uygulayabilirsiniz. Bu bolum guvenlik tarafina odaklanir: tehlikeli islemleri engelleme, uyumluluk icin kayit tutma ve politika uygulamasini merkezilestirme.

PreToolUse Engelleme

PreToolUse olayi, eslestirilen her arac cagrisi oncesinde calisir ve hook’unuza girdiyi inceleme ve calistirmayi engelleme firsat verir. Cikis kodu 2 ile cikan bir hook, aracin calismasini tamamen onler. Stderr’e yazdiginiz hata mesaji, Claude’a eylemin neden reddedildigine dair neden olarak geri beslenir.

Bunu .claude/settings.json dosyaniza ekleyin:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

.claude/hooks/block-dangerous.sh dosyasindaki hook betigi:

#!/usr/bin/env bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

BLOCKED=(
  "rm -rf /"
  "rm -rf ~"
  "DROP TABLE"
  "DROP DATABASE"
  "> /dev/sda"
  "mkfs."
  ":(){ :|:& };:"
)

for pattern in "${BLOCKED[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "ENGELLENDI: '$pattern' kalibi eslesti" >&2
    exit 2  # Cikis kodu 2 = Arac cagrisini ENGELLE
  fi
done

exit 0  # Cikis kodu 0 = izin ver

Claude engellenmis bir kalip iceren herhangi bir komutu calistirmayi denediginde, hook calisir, arac cagrisi onlenir ve Claude nedenini aciklayan stderr mesajini alir. matcher alani bir regex’tir — "Bash" yalnizca Bash arac cagrilarini hedefler. Dosya islemlerini kapsamak icin "Bash|Edit|Write" ile genisletebilir veya tum MCP arac cagrilarini korumak icin "mcp__.*" kullanabilirsiniz.

Ayni dizideki birden fazla hook sirayla calisir. Cikis kodu 2 ile cikan ilk hook kazanir — zincirdeki sonraki hook’lar atlanir ve arac cagrisi engellenir.

Denetim Kaydi

Uyumluluk ve adli analiz icin Claude’un yaptigini her seyin kaydina ihtiyaciniz var. PostToolUse hook’lari bir arac basariyla calistiktan sonra calisir ve denetim kaydi icin dogru yerdir — arac zaten calismistir, dolayisiyla hook onu engelleyemez, ancak ne olduguna dair tam baglami kaydedebilir.

.claude/settings.json dosyasina bir PostToolUse kayit hook’u ekleyin:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/audit-log.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

.claude/hooks/audit-log.sh dosyasindaki kayit betigi:

#!/usr/bin/env bash
INPUT=$(cat)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
TOOL=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"

LOG_DIR="$PROJECT_DIR/.claude/logs"
mkdir -p "$LOG_DIR"

echo "${TIMESTAMP}|${TOOL}|${TOOL_INPUT}" >> "$LOG_DIR/audit.log"
exit 0

Iki onemli detaya dikkat edin. Ilk olarak hook, matcher alanini atlar — eslestirici yok her arac turu icin calisir demektir, Bash komutlarini, dosya duzenlemelerini, MCP cagrilarini ve diger her seyi yakalar. Ikinci olarak, "async": true hook’u arka planda calistirir boylece kayit tutma Claude’un calismasini yavaslatmaz. Bu bir PostToolUse hook oldugu icin, cikis kodu 2 hicbir seyi geri almaz — arac zaten calismistir.

Izin verilen islemleri yakalamak icin PreToolUse olaylarini da kaydedebilirsiniz. Birlikte, Pre ve Post kayitlari tam bir resim sunar: ne denendi, neye izin verildi ve ne oldu.

Dogrulama Icin Command Hook’lari

Kabuk tabanli command hook’lari, girdi dogrulama olusturmanin en basit yoludur. Hook, tam arac cagrisi veri yukunu stdin uzerinden JSON olarak alir, bu da betiginizin izin vermek veya engellemek konusunda karar vermeden once arac girdisinin herhangi bir yonunu ayristirip inceleyebilecegi anlamina gelir.

Belirli korunan yollara yazma islemlerini engelleyen daha hedefli bir dogrulayici:

#!/usr/bin/env bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
FILE_PATH=""

if [ "$TOOL" = "Edit" ] || [ "$TOOL" = "Write" ]; then
  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
elif [ "$TOOL" = "Bash" ]; then
  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
fi

PROTECTED=(".env" "credentials" "secrets" "id_rsa" ".ssh/")

for pattern in "${PROTECTED[@]}"; do
  if echo "$FILE_PATH" | grep -qi "$pattern"; then
    echo "ENGELLENDI: '$pattern' ile eslesen korunmus yol uzerinde islem" >&2
    exit 2
  fi
done

exit 0

Hem dosya islemlerini hem de Bash komutlarini kapsamak icin genis bir eslestirici ile ayarlara baglama:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/protect-paths.sh"
          }
        ]
      }
    ]
  }
}

Command hook’lari hizli olmalidir. PreToolUse hook’lari eslestirilen her arac cagrisini kapidigi icin, 500ms’nin uzerindeki herhangi bir sey Claude’un yavas hissetmesine neden olur. Dogrulama mantginii basit tutun — kalip eslestirme ve dize kontrolleri, ag cagrilari veya agir hesaplama degil.

Merkezi Politika Icin HTTP Hook’lari

Merkezi kontrol gerektiren takimlar icin, HTTP hook’lari arac cagrisi veri yukunu bir politika sunucusuna POST istegi olarak gonderir. Bu, kabuk betiklerini her gelistirici makinesine dagitmak yerine tek bir uc noktadan kurum genelinde kurallar uygulamaniza olanak tanir.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/validate",
            "headers": {"Authorization": "Bearer $POLICY_TOKEN"},
            "allowedEnvVars": ["POLICY_TOKEN"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Politika sunucusu, tam hook girdisini POST govdesi olarak alir ve bir JSON karar ile yanitlar. Sunucu tarafindan bir arac cagrisini engellemek icin decision ve reason alanlariyla bir JSON govdesi dondurulur:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Komut DROP TABLE iceriyor"
  }
}

permissionDecision alani uc degeri destekler: onaylamak icin "allow", engellemek icin "deny" veya normal izin istemine gecmek icin "ask". Bu, politika sunucusuna ince taneli kontrol saglar — bilinen tehlikeli kaliplari kesin olarak engelleyebilir, bilinen guvenli islemleri otomatik onaylayabilir ve belirsiz durumlari kullaniciya birakabilir.

HTTP hook’larinin varsayilan zaman asimi 30 saniyedir, ancak guvenlik dogrulamasi icin bunu kisa tutmaniz gerekir (5 saniye veya daha az). Politika sunucusu erisilemezse ve istek zaman asimina ugrarsa, hook engellemeyen bir hata olarak islenir — arac cagrisi devam eder. Mimarinizi bu acik-basarisiz davranisini goz onunde bulundurarak tasarlayin.

Guvenlik Hook Kaliplari

Hook’lar vs CLAUDE.md: Hangisini Ne Zaman Kullanmali

Hook’lar ve CLAUDE.md arasindaki uygulama farki guvenlik icin kritiktir:

• Hook’lar = deterministik uygulama. Cikis kodu 2 ile cikan bir PreToolUse hook islemi her zaman engeller. Hicbir istem, hicbir CLAUDE.md talimati, hicbir konusma baglami bunu gecersiz kilamaz. Hook’lar, Claude’un akil yurumesi disinda kabuk surecleri olarak calisir — istem enjeksiyonuna veya ikna etmeye tabi degildir.

• CLAUDE.md = tavsiye niteiginde yonlendirme. CLAUDE.md’deki talimatlar, sistem isteminin bir parcasi olarak Claude’un baglamina yuklenir. Claude bunlari en iyi caba yonlendirmesi olarak izler, ancak yeterince ikna edici istem enjeksiyonlari, karmasik gorev akislari veya sikistirma sirasinda baglam penceresi baskisi tarafindan gecersiz klinabilir.

Hook’lari su durumlarda kullanin: Asla ihlal edilmemesi gereken guvenlik acsindan kritik kurallar — uretim yapilandirmalarinizin yazmesinin engellenmesi, harici URL’lere curl’un onlenmesi, tum Bash komutlarinin denetlenmesi, commit’lerden once test calistirilmasinin zorunlu tutulmasi.

CLAUDE.md’yi su durumlarda kullanin: Gelistirme tercihleri ve kurallari — kodlama stili, yanit formati, proje mimari kararlari, sikistirma talimatlari, is akisi tercihleri.

Yaygin hata, guvenlik kurallarini CLAUDE.md’ye koyup uygulanmasini beklemektir. “Sormadan asla dosya silme” diyen bir CLAUDE.md talimati yararli bir yonlendirmedir, ancak kotu amacli bir dosyadaki istem enjeksiyonu bunu gecersiz kilabilir. rm komutlarini kontrol eden bir PreToolUse hook ise Claude’un baglaminda ne olursa olsun gecersiz kilinamaz.