Claude Code Mods: fail-open deneyi, ölçümler, kontrol listesi ve kaynaklar

TL;DR

• Bir Claude Code Mod'u üç dosyadan oluşur: .claude-plugin/plugin.json, içinde {"modules":["./index.ts"]} bulunan hooks/hooks.json ve register(on) export eden bir TypeScript modülü. Yüklenmesi için başka bir şey gerekmez.
• 2.1.272 sürümünde /plugin-types komutunun yazdığı tipli yüzey, claude-code.d.ts içinde 11,783 satırdır: 23 grup altında 84 olay veya çağrı adı. fs.readFile kalktı, artık fs.read ve fs.write var.
• 42 satırlık bir tool.call hook'u, modelin hem Read hem Bash aracında gerçek anahtar yerine API_KEY=[REDACTED] okumasını sağladı: sağlıklı bir geçiş başına 27.9 ms ve oturuma eklenen yaklaşık 0 token.
• 10 sn bütçesini aşan veya hata fırlatan bir hook atlanır ve altındaki komut çalışır. Log bunu söyler, ama sonuç bir bypass'tır: koruyucu bir Mod hata durumunda açık kalır (fail-open).
• Üretilen yol çalışıyor: tek bir cümle, yaklaşık 4 dakikada ve $1.23'a 190 satırlık bir Mod ile 53 satır test üretti. claude plugin validate uyarısız geçti, claude plugin test 4 pass / 0 fail verdi.
• Bir şey yeniden üretilemedi: Mod claude -p altında yüklendi, ama pty ile sürülen etkileşimli REPL'de iki denemede de sessiz kaldı. Gerçek bir terminalde test edene kadar REPL'de yüklenmeyi doğrulanmamış sayın.

Ölçümler ne söylüyor

Aşağıdakilerin hepsi, CLAUDE_CODE_ENABLE_FUNCTION_HOOKS ayarlı Claude Code 2.1.272 üzerinde çalıştırıldı: elle yazılmış redact-secrets adlı bir Mod'da ve onu kırmak için kurulan üç tek kullanımlık Mod'da. Özelliğin kendisi, hâlâ resmi spesifikasyona en yakın şey olan Function Hooks öneri issue'sunda izleniyor s3.

Araçlar dokümantasyondan önce geldi. 2.1.272 sürümü claude plugin validate, test, eval ve details ile geliyor; plugin --help komut bloğunda listelemese de test çalışıyor s3. Bir oturumda /plugin-types çalıştırmak .claude/types/claude-code.d.ts içine 11,783 satır yazdı, ayrıca 7 sunucudan 150 MCP aracını kapsayan 3,438 satırlık bir claude-code-mcp.d.ts oluşturdu s3. Üretilen tipleri saymak 23 grup üzerinde 84 olay veya çağrı adı veriyor ve dosya, Eylül yazılarında okumuş olabileceğiniz bir şeyi yeniden adlandırıyor: fs.readFile artık yok, yüzey fs.read ve fs.write s9. Aynı tipler, bir tool.call hook'unun { result, context? } veya { deny } döndürdüğünü söylüyor; text ve ref çekirdekten gelir ve hook'un kendi cevabının parçası değildir, yani text değil result yeniden yazılır s3.

claude plugin validate, Mod hiç çalışmadan önce bir footprint basar: ./index.ts hooks: tool.call ve ./index.ts calls: $.ui.toast, veya modül hiçbir host yeteneğine dokunmuyorsa calls: nothing on $ s4. Bu statik satır, awesome-claude-code-mods gibi bir dizinin bugün otomatikleştirebildiği tek incelemedir ve bir sonraki paragraf için önemlidir.

Redaksiyon -p modunda çalışıyor. 42 satırlık hook tool.call'u yakaladı ve dosyada ile shell çıktısında sk-test1234567890abcdef olan yerde model API_KEY=[REDACTED] aldı, hem Read hem Bash aracı için s3. Debug logu sağlıklı bir geçişi, worker geçişi ve next() dahil, 27.9 ms gidiş dönüş olarak ölçtü s3. claude plugin details Mod'u her oturuma eklenen yaklaşık 0 token olarak fiyatladı: Mod, prompt metni değil süreç içindeki koddur ve savunucularının shell hook'lara ve skill'lere karşı ana argümanı budur s7.

Koruyucu hata durumunda açık kalıyor. 15 sn uyuyan bir slow-guard Mod'u 10 sn bütçesinde kesildi, mesaj hook failed: slow-guard: exceeded 10000ms budget (tool.call; skipped; what is below it ran in its place) oldu ve echo hi yine de çalıştı s3. Hata fırlatan bir throw-guard Mod'u aynı şekilde atlandı: hook failed: throw-guard: boom (tool.call; skipped; what is below it ran in its place), süre 574.2 ms s3. Logda gürültülü, sonuçta bypass. Bir şeyi engellemek işi olan her Mod'u bunu akılda tutarak okuyun: koruyucudaki bir hata çökme değil, bir delik demektir.

Üretim ucuz. Tek bir cümleden model, yaklaşık 4 dakikada, 34 turda ve $1.23'a çalışan 190 satırlık bir Mod ile 53 satır test yazdı (19,053 çıktı token'ı, 497,282 cache okuma, 8,357 düşünme token'ı) s3. Bu Mod claude plugin validate'i uyarısız, claude plugin test'i 0.31 sn'de 4 pass / 0 fail ile geçti ve anahtarları canlı olarak gizledi s3. Elle yazılmış Mod'da claude plugin test, API anahtarı ve model çağrısı olmadan çalıştı: 0.25 sn'de 1 pass s3. Ajanlara Mod yazmayı öğreten bir skill zaten var, bir şablonla deneyi tekrarlamak isterseniz s12.

Yeniden üretilemeyen: pty ile sürülen REPL'de Mod 2 denemede yüklenmediği için $.ui.toast hiç görünmedi; -p içinde karşılığı yalnızca bir debug satırı olarak göründü. X'te dolaşan "yalnızca REPL" iddiasının tersi gözlendi ve kök neden izole edilemedi s8. 5 sn'lik takılı worker heartbeat'i de test edilmedi; yalnızca 10 sn'lik await bütçesi ve hata fırlatma yolu ölçüldü.

Ölçümler

Protokol: Claude Code 2.1.272, function hooks bir ortam değişkeniyle açık. Her Mod, plugin.json, hooks/hooks.json ve tek bir index.ts içeren bir plugin dizinidir. Çalıştırmalar debug logu açık claude -p ile yapıldı; yerleştirilen bir dosya ve bir shell komutu sk-test1234567890abcdef içeriyordu. Fail-open durumları 15 sn uyuyan bir Mod ve hata fırlatan bir Mod ile, korunan komut olarak echo hi kullanılarak sürüldü. Etkileşimli REPL pty ile sürüldü ve iki denemede Mod'u yüklemedi.

Pazartesi yapılacaklar

• Bir oturumda /plugin-types çalıştırın ve .claude/types/claude-code.d.ts dosyasını açın: Eylül'den kalma herhangi bir kod parçasına güvenmeden önce fs.read ve tool.call arayın.
• Üç dosyalı Mod iskeletini yazın (plugin.json, {"modules":["./index.ts"]} içeren hooks/hooks.json, register(on) export eden index.ts) ve üzerinde claude plugin validate çalıştırın: hooks: ve calls: footprint satırlarını okuyun.
• En çok kullandığınız shell hook'u result'ı yeniden yazan bir tool.call handler'ına taşıyın, sonra debug logundaki geçiş süresini shell sürümüyle karşılaştırın.
• Mod'un yanına bir claude plugin test dosyası ekleyin, böylece koruyucu CI'da API anahtarı olmadan çalışsın.
• Her koruyucu handler'ı, hata durumunda { deny } döndüren bir try/catch ile sarın: bu sürümde bir istisna veya 10 sn'lik takılma sizi atlar ve komutun geçmesine izin verir.
• Mod'u claude -p altında ve gerçek etkileşimli terminalinizde ayrı ayrı test edin ve hangisinde yüklendiğini not edin.
• Üçüncü taraf bir Mod'u kurmadan önce üzerinde claude plugin validate çalıştırın ve calls: satırında Mod'un kullanmak için hiçbir nedeni olmayan host yeteneklerini sayanları reddedin.

Daha fazlası için

• Öneri issue'sunu baştan sona okuyun, yorumlardaki mimari PDF'i dahil: register(on), bütçeler ve worker geçişi için yazılı tek sözleşme budur s3.
• Host sürecinde bir ModApi'ye karşı TypeScript çalıştıran Command Code Mods tasarımıyla karşılaştırın: iki sistem aynı şekli ve erken erişim kısıtını paylaşıyor s2.
• claudefa.st önizlemesi özellik hâlâ bir öneriyken yazıldı: 3 Eylül metni ile 2.1.272 binary'si arasında neyin değiştiğini görmek için faydalı s9.
• Prathkum'un notu, süreç içi hook'ların token ve gecikmede shell hook'lardan neden iyi olduğunu anlatan en net kısa açıklama s7.
• cc-mod-waitwhat okumak için iyi bir ilk Mod: prompt'un üstünde UI, transkripte hiçbir şey yazılmıyor s11.
• cc-arcade, $.ui'nin ne kadar uzağa uzandığını gösteriyor: bir Mod'dan prompt'un üstünde çizilen oyunlar s5.
• Hooks referansı hâlâ shell modelini anlatıyor; her eski olayı yeni noun.event adıyla eşlemek için açık tutun s1.
• X'teki şüpheciler plugin'lerin bunu zaten karşıladığını ve yüzeyin her sürümde kırılacağını savunuyor; yeniden adlandırılan fs grubu onlar için bir veri noktası s23.

Kaynaklar

• Function Hooks proposal (issue #91870), GitHub, anthropics/claude-code. Neden okunmalı: Mod'lar için spesifikasyona benzeyen tek metin, yorumlarda mimari PDF'i ve sevkiyat izi ile.
• Hooks reference, Claude Code docs. Neden okunmalı: geçiş yaptığınız shell hook modeli, olay olay.
• Command Code Mods documentation, Command Code. Neden okunmalı: aynı süreç içi TypeScript şekline sahip öncül, Anthropic'in neyi kopyaladığını veya neyden kaçındığını görmek için faydalı.
• awesome-claude-code-mods, GitHub, karanb192. Neden okunmalı: herkese açık Mod'ların otomatik taranan dizini, tek incelemesi validate footprint'i.
• cc-arcade, GitHub, sezaakgun. Neden okunmalı: özelliği görünür kılan demo ve $.ui turu.
• Boris Cherny announcement tweet, X, Boris Cherny. Neden okunmalı: blog yazısı olmadığı için bir Anthropic mühendisinden lansman açıklaması.
• Prathkum: Function Hooks explained, X, Prathkum. Neden okunmalı: zaten shell hook yazan biri için hook ve Mod farkının en iyi kısa açıklaması.
• shipnotesai reaction thread, X, shipnotesai. Neden okunmalı: "yalnızca REPL" iddiasının dolaştığı yer, bizim çalıştırmamız bunu yalanladı.
• Claude Code Function Hooks: Preview Behind a Flag, claudefa.st. Neden okunmalı: sürüm öncesi açıklama, öneriyi binary ile karşılaştırmak için iyi.
• cc-mod-waitwhat, GitHub, GGGODLIN. Neden okunmalı: transkripte değil UI'ya yazan küçük, okunaklı bir Mod.
• claude-mods-skill, GitHub, BeLazy167. Neden okunmalı: tek cümlelik deneyi tekrarlamak isterseniz Mod üreten bir skill.
• AxialisSoftware reaction, X, AxialisSoftware. Neden okunmalı: şüpheci görüş, tek bir tweet'te.

FAQ

Bir Mod bugün shell hook'larımın yerini alıyor mu?

Engellemesi gereken hiçbir şey için henüz değil. 2.1.272'de hata fırlatan veya 10 sn'yi aşan bir hook atlanır ve komut çalışır. Shell hook'lar çalışmaya devam eder, bu yüzden engelleyenleri, bildirilmiş bir catch veya fail-closed seçeneği gelene kadar orada tutun.

Mod sorunsuz çalışıyorsa validate neden önemli?

Çünkü hooks: ve calls: satırları, bir Mod'un $ üzerinde neye dokunduğunu gösteren tek statik görünümdür. Kendi Mod'unuz için footprint'i doğrular; üçüncü taraf bir Mod için, kod sürecinizde çalışmadan önce aldığınız incelemenin tamamıdır.

Bir Mod oturum başına ne kadar maliyetli?

claude plugin details yaklaşık 0 eklenen token bildirdi. Mod, prompt'ta metin değil motorda çalışan koddur ve bir skill veya CLAUDE.md kuralına göre ana avantajı budur.

Mod neden -p içinde yüklendi ama REPL'de yüklenmedi?

Bilinmiyor. claude -p hook'u yükleyip uygularken pty ile yapılan iki deneme sessiz kaldı. Olası neden özelliğin kendisi değil pty ortamı, bu yüzden iki yönden birine güvenmeden önce kendi terminalinizde test edin.