Bu sayfa İngilizce belgenin çevirisidir. Komutlar, tanımlayıcılar ve örnekler aynıdır. Çalışma zamanı 7.24.4 · SDK 2.6.7. İngilizce kaynak

Yaşam döngüsü kancaları

Durum: Etkin Kapsam: güncel durum Son inceleme: 2026-08-23 Sahip: ax-code çalışma zamanı

Yaşam döngüsü kancaları, çalışma zamanını yeniden derlemeden ajan olaylarında kabuk komutları çalıştırmanızı sağlar. İzin kurallarını ve yalıtım sandbox’ını tamamlarlar: kancalar belirleyici yan etkilerdir (“her zaman biçimlendir”, “asla force-push yapma”), istemler ise danışma amaçlı kalır.

Olaylar

Dört oturum yaşam döngüsü olayı (SessionStart, SessionEnd, PostCompact, Interrupt) ve PostToolUseFailure yalnızca gözlemdir: ateşlenir ve unutulur, yaşam döngüsü yolunu asla engellemez ve yükleri yalnızca kimlik/gerekçe/zaman damgası taşır — konuşma metni, özet veya araç çıktısı asla taşımaz. Alt ajan oturumları SessionStart ateşlemez (zaten SubagentStop üzerinden görünürler). SubagentStop hem task hem task_parallel tarafından başlatılan çocuklar için ateşlenir.

PostToolUse geri bildirimi modele ulaşır

Bir PostToolUse kancası modele metin geri verebilir. Araç sonucuna bir <hook_feedback event="PostToolUse"> bloğu içinde, aracın kendi çıktısından sonra eklenir; çıktının yerini asla almaz ve asla engellemez.

• Eski girdiler (protocol yok): 0 çıkış koduyla biten bir kancanın kırpılmış stdout’u.
• protocol: "claude-code" girdileri: hookSpecificOutput.additionalContext, bir reason değeri ({"decision": "block", "reason": "..."} kararı) veya kanca 2 ile çıktığında stderr. Diğer sıfır olmayan çıkışlar hiçbir şey katmaz.

Geri bildirim kanca başına 4,000 karakter ve araç çağrısı başına 8,000 karakterle sınırlıdır; gürültülü bir kanca bağlamı basamaz. format-after-edit paketini yararlı kılan budur: anımsatıcısı artık yalnızca günlükte değil, modelin sonraki turuna iner.

Bu adlar AX Code iç eklenti tetiklerine (tool.execute.before / tool.execute.after) artı oturum düzeyi istem, sıkıştırma, alt ajan ve duruş kancalarına eşlenir. Sentetik devam istemleri (iç agentRouting: "preserve" istemleri) UserPromptSubmit ateşlemez.

Paketleri açın

Proje kancaları ve eklentileri depo denetimli kod yürütür; bu yüzden .ax-code/hooks.json, .ax-code/plugin/ ve proje yapılandırmalı eklentiler varsayılan olarak kapalıdır. Onları inceledikten sonra AX Code’u başlatırken deponun dışında kabul edin:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Ardından projenizde .ax-code/hooks.json oluşturun:

{
  "packs": ["format-after-edit", "block-force-push", "require-tests-on-stop", "protect-env-files", "log-bash-commands"]
}

Resmi paketler (≥5)

Özel kancalar:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "echo running bash",
      "blockOnFailure": false
    }
  ]
}

Claude Code hat protokolü (isteğe bağlı)

Claude Code için yazılmış kancalarınız varsa bir girdi "protocol": "claude-code" ile Claude Code hat protokolüne kabul edebilir:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "my-claude-code-hook.sh",
      "protocol": "claude-code"
    }
  ]
}

Engellenebilir olaylar (PreToolUse, UserPromptSubmit) için kabul edilen girdiler blockOnFailure denetimi yerine Claude Code anlamıyla çözülür:

• Çıkış 2 eylemi engeller; kancanın stderr’i gerekçe olarak gösterilir. Bozuk stdout yine engeller (güvenli başarısız).
• Çıkış 0 ve stdout JSON {"permissionDecision": "allow"|"deny"|"ask", "reason"?}: allow devam eder; deny, reason ile engeller; ask araç çağrısını gerekçeyi gösteren etkileşimli bir hook izin isteminde duraklatır (varsayılan "hook requested user confirmation"). İstem yalnızca etkileşimlidir: hiçbir always kuralı, joker verme veya otonom otomatik onay onu yanıtlayamaz ve başsız bir çalıştırma onu reddeder; model bunu olağan bir izin reddi olarak görür. Daha sonra deny yanıtlayan bir kanca, daha önceki ask üzerine kazanır. UserPromptSubmit bir istem bağlanacak araç çağrısına sahip değildir; bu yüzden ask orada yine engeller. İç içe Claude Code biçimi {"hookSpecificOutput": {"permissionDecision": "...", "permissionDecisionReason": "..."}} takma ad olarak kabul edilir.
• Başka herhangi bir çıkış engellemeyen bir hatadır (günlüğe yazılır, eylem devam eder).

Yalnızca gözlem olayları çözücüyü tümüyle yok sayar — asla engelleyemezler. protocol alanı olmayan girdiler eskisi gibi davranır.

Kanca komutlarına sunulan ortam değişkenleri:

• HOOK_EVENT — olay adı sırasıyla PreToolUse, sonra PostToolUse, sonra PostToolUseFailure, sonra Stop, sonra UserPromptSubmit, sonra PreCompact, sonra SubagentStop, sonra SessionStart, sonra SessionEnd, sonra PostCompact, sonra Interrupt
• HOOK_TOOL — araç kimliği
• HOOK_SESSION_ID
• HOOK_ARGS_JSON — JSON araç bağımsız değişkenleri
• HOOK_ARGS_STDIN=1 — tam JSON bağımsız değişkenleri stdin üzerinde her zaman vardır; 32 KiB’den büyük yüklerde HOOK_ARGS_JSON boştur
• HOOK_PACK — uygulanabilirse paket adı

Kanca alt süreçleri AX Code ortamının temizlenmiş bir sürümünü devralır. AX Code olağan platform ve araç değişkenlerini korur ancak gizli benzeri adları, kimlik bilgisi taşıyan URL’leri, SSH_AUTH_SOCK gibi kimlik bilgisi yardımcılarını ve NODE_OPTIONS gibi süreç enjeksiyonu değişkenlerini kaldırır. Yukarıdaki HOOK_* protokol değişkenleri temizlikten sonra eklenir ve her zaman vardır.

Ortam kimlik bilgileri gerektiren tam güvenilen eski kancalar, önceki davranışı deponun dışında geri getirebilir:

AX_CODE_HOOKS_FULL_ENV=1 AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Bu kaçış kapağı her ortam değişkenini her açık kancaya gösterir. Bir depo bunu .ax-code/hooks.json üzerinden isteyemez; yalnızca tüm kancaları ve paketleri inceledikten sonra kullanın.

Güvenlik notu: ortam temizliği ortam kimlik bilgisi açıklığını azaltır ancak kanca komutlarını sandbox’a almaz. Kancalar erişilebilir dosyaları okuyabilen ve konak ağını kullanabilen rastgele kabuk kodu olarak kalır. Onları güvenilen kod olarak ele alın ve açık her kancayı ve paketi inceleyin.

Yalıtımla ilişki

Kancalar sandbox’ın yerini almaz. Şunları kullanın:

1. Taşınabilir yazma/ağ sınırları için uygulama yalıtımı
2. Varsa çekirdek zorlamalı bash sandbox’ı için işletim sistemi yalıtımı (varsayılan "auto" arka ucu)
3. İlke yan etkileri ve force-push gibi sert engeller için kancalar

Bkz. Sandbox kipi ve SECURITY.md.