AIDive

Paket video

Claude Code Mods: eksperimen fail-open, pengukuran, checklist, dan sumber

10 menit baca

TL;DR

  • Sebuah Claude Code Mod terdiri dari tiga file: .claude-plugin/plugin.json, hooks/hooks.json berisi {"modules":["./index.ts"]}, dan modul TypeScript yang mengekspor register(on). Tidak ada yang lain yang dibutuhkan agar Mod termuat.
  • Di build 2.1.272, tipe yang ditulis oleh /plugin-types berukuran 11,783 baris claude-code.d.ts: 84 nama event atau call di atas 23 noun. fs.readFile sudah tidak ada, noun-nya adalah fs.read dan fs.write.
  • Hook tool.call sepanjang 42 baris membuat model membaca API_KEY=[REDACTED] alih-alih key aslinya, baik untuk tool Read maupun Bash, dengan 27.9 ms per hop sehat dan sekitar 0 token tambahan di sesi.
  • Hook yang tidur melewati budget 10 s atau melempar error akan dilewati, lalu perintah di bawahnya tetap jalan. Log mencatatnya, tetapi efeknya adalah bypass: Mod penjaga fail open.
  • Jalur generate berfungsi: satu kalimat menghasilkan Mod 190 baris plus 53 baris tes dalam sekitar 4 menit dan $1.23, lolos claude plugin validate tanpa peringatan dan claude plugin test 4 pass / 0 fail.
  • Satu hal tidak bisa direproduksi: Mod termuat di bawah claude -p tetapi diam di REPL interaktif yang digerakkan lewat pty, dua kali percobaan. Anggap pemuatan di REPL belum terverifikasi sampai Anda mengujinya di terminal asli.

Apa kata hasil pengukuran

Semua yang di bawah ini dijalankan di Claude Code 2.1.272 dengan CLAUDE_CODE_ENABLE_FUNCTION_HOOKS diaktifkan, pada Mod tulisan tangan bernama redact-secrets dan tiga Mod sekali pakai yang dibuat untuk merusaknya. Fiturnya dilacak di issue proposal Function Hooks, yang masih menjadi hal terdekat dengan spesifikasi resmi s3.

Tooling-nya ada sebelum dokumentasinya. Build 2.1.272 menyertakan claude plugin validate, test, eval dan details; test berfungsi meskipun plugin --help tidak mencantumkannya di blok perintah s3. Menjalankan /plugin-types di dalam sesi menulis 11,783 baris ke .claude/types/claude-code.d.ts, ditambah claude-code-mcp.d.ts sepanjang 3,438 baris yang mencakup 150 tool MCP dari 7 server s3. Menghitung tipe yang dihasilkan memberi 84 nama event atau call di atas 23 noun, dan file itu mengganti nama satu hal yang mungkin Anda baca di postingan September: fs.readFile tidak ada lagi, permukaannya adalah fs.read dan fs.write s9. Tipe yang sama menyatakan hook tool.call mengembalikan { result, context? } atau { deny }; text dan ref berasal dari core dan bukan bagian jawaban hook itu sendiri, jadi yang Anda tulis ulang adalah result, bukan text s3.

claude plugin validate mencetak footprint sebelum Mod sempat berjalan: ./index.ts hooks: tool.call dan ./index.ts calls: $.ui.toast, atau calls: nothing on $ bila modul tidak menyentuh kapabilitas host apa pun s4. Baris statis ini adalah satu-satunya penyaringan yang bisa diotomatisasi direktori seperti awesome-claude-code-mods saat ini, dan itu penting untuk paragraf berikutnya.

Redaksi berfungsi di mode -p. Hook 42 baris itu mencegat tool.call, dan model menerima API_KEY=[REDACTED] di tempat file dan output shell berisi sk-test1234567890abcdef, baik untuk tool Read maupun tool Bash s3. Log debug mencatat satu hop sehat pada 27.9 ms round trip, termasuk worker hop dan next() s3. claude plugin details menghitung Mod ini sekitar 0 token tambahan di setiap sesi: Mod adalah kode di dalam proses, bukan teks prompt, dan itu argumen utama para pendukungnya melawan shell hook dan skill s7.

Penjaga ini fail open. Mod slow-guard yang tidur 15 s dipotong di budget 10 s dengan hook failed: slow-guard: exceeded 10000ms budget (tool.call; skipped; what is below it ran in its place), dan echo hi tetap jalan s3. Mod throw-guard yang melempar error dilewati dengan cara yang sama, hook failed: throw-guard: boom (tool.call; skipped; what is below it ran in its place), tercatat 574.2 ms s3. Berisik di log, tembus dalam efek. Mod apa pun yang tugasnya memblokir sesuatu harus dibaca dengan catatan ini: bug di penjaga adalah lubang, bukan crash.

Generate itu murah. Dari satu kalimat, model menulis Mod 190 baris yang berfungsi plus 53 baris tes dalam sekitar 4 menit, 34 turn dan $1.23 (19,053 output token, 497,282 cache-read, 8,357 thinking) s3. Mod itu lolos claude plugin validate tanpa peringatan dan claude plugin test dengan 4 pass / 0 fail dalam 0.31 s, dan menyembunyikan key secara langsung s3. Pada Mod tulisan tangan, claude plugin test berjalan tanpa API key dan tanpa panggilan model: 1 pass dalam 0.25 s s3. Skill yang mengajari agen menulis Mod sudah ada kalau Anda ingin mengulang ini dengan template s12.

Yang tidak bisa direproduksi: $.ui.toast tidak pernah tampil karena Mod tidak termuat di REPL yang digerakkan lewat pty dalam 2 percobaan; di -p hal yang setara hanya muncul sebagai baris debug. Kebalikan dari klaim "hanya REPL" yang beredar di X teramati, dan akar masalahnya tidak diisolasi s8. Heartbeat 5 s untuk worker yang macet juga tidak diuji; hanya budget await 10 s dan jalur throw yang diukur.

Pengukuran

Kasus Apa yang dilakukan Mod Hasil Waktu
redact-secrets, tool Read Menulis ulang result pada tool.call Model melihat API_KEY=[REDACTED] 27.9 ms per hop
redact-secrets, tool Bash Hook yang sama, output shell Model melihat API_KEY=[REDACTED] 27.9 ms per hop
slow-guard Tidur 15 s di dalam tool.call Dilewati, echo hi jalan dipotong di 10000 ms
throw-guard Melempar boom di dalam tool.call Dilewati, perintah jalan 574.2 ms
Mod hasil generate 190 baris + 53 baris tes dari satu kalimat validate: tanpa peringatan; test: 4 pass / 0 fail ~4 min, 34 turn, $1.23
claude plugin test pada redact-secrets Tanpa API key, tanpa panggilan model 1 pass 0.25 s
claude plugin details Biaya sesi dari Mod ~0 token tambahan n/a

Protokol: Claude Code 2.1.272, function hooks diaktifkan lewat environment variable. Setiap Mod adalah direktori plugin dengan plugin.json, hooks/hooks.json dan satu index.ts. Eksekusi lewat claude -p dengan debug logging menyala; file yang ditanam dan perintah shell sama-sama berisi sk-test1234567890abcdef. Kasus fail-open digerakkan oleh Mod yang tidur 15 s dan Mod yang melempar error, dengan echo hi sebagai perintah yang dijaga. REPL interaktif digerakkan lewat pty dan tidak memuat Mod dalam dua percobaan.

Kerjakan hari Senin

  • Jalankan /plugin-types di sebuah sesi dan buka .claude/types/claude-code.d.ts: cari fs.read dan tool.call sebelum mempercayai snippet dari postingan September mana pun.
  • Tulis kerangka Mod tiga file (plugin.json, hooks/hooks.json dengan {"modules":["./index.ts"]}, index.ts yang mengekspor register(on)) lalu jalankan claude plugin validate: baca baris footprint hooks: dan calls:.
  • Porting shell hook yang paling sering Anda pakai ke handler tool.call yang menulis ulang result, lalu bandingkan waktu hop di log debug dengan versi shell.
  • Tambahkan file claude plugin test di sebelah Mod agar penjaga berjalan tanpa API key di CI.
  • Bungkus setiap handler penjaga dengan try/catch yang mengembalikan { deny } saat gagal: di build ini exception atau stall 10 s membuat penjaga dilewati dan perintah lolos.
  • Uji Mod di bawah claude -p dan di terminal interaktif asli Anda secara terpisah, dan catat mana yang memuatnya.
  • Sebelum memasang Mod pihak ketiga, jalankan claude plugin validate padanya dan tolak apa pun yang baris calls:-nya menyebut kapabilitas host yang tidak punya alasan dipakai Mod itu.

Pelajari lebih lanjut

  • Baca issue proposal sampai tuntas, termasuk PDF arsitektur yang dilampirkan di komentar: itu satu-satunya kontrak tertulis untuk register(on), budget dan worker hop s3.
  • Bandingkan dengan desain Command Code Mods, yang menjalankan TypeScript terhadap ModApi di proses host: kedua sistem punya bentuk dan gating early-access yang sama s2.
  • Preview claudefa.st ditulis saat fiturnya masih proposal: berguna untuk melihat apa yang berubah antara teks 3 Sep dan binary 2.1.272 s9.
  • Catatan tweet Prathkum adalah pernyataan singkat paling jelas tentang mengapa hook in-process mengalahkan shell hook dalam token dan latensi s7.
  • cc-mod-waitwhat adalah Mod pertama yang bagus untuk dibaca: UI di atas prompt, tanpa menulis apa pun ke transkrip s11.
  • cc-arcade menunjukkan sejauh mana jangkauan $.ui: game dirender di atas prompt dari sebuah Mod s5.
  • Referensi hooks masih menjelaskan model shell; biarkan terbuka untuk memetakan tiap event lama ke nama noun.event yang baru s1.
  • Para skeptis di X berargumen bahwa plugin sudah mencakup ini dan permukaannya akan rusak di setiap rilis; noun fs yang berganti nama adalah satu titik data bagi mereka s23.

Sumber

  • Function Hooks proposal (issue #91870), GitHub, anthropics/claude-code. Mengapa dibaca: satu-satunya teks mirip spesifikasi untuk Mods, lengkap dengan PDF arsitektur dan jejak peluncuran di komentar.
  • Hooks reference, Claude Code docs. Mengapa dibaca: model shell hook yang sedang Anda tinggalkan, event demi event.
  • Command Code Mods documentation, Command Code. Mengapa dibaca: prior art dengan bentuk TypeScript-in-process yang sama, berguna untuk melihat apa yang ditiru atau dihindari Anthropic.
  • awesome-claude-code-mods, GitHub, karanb192. Mengapa dibaca: direktori Mod publik hasil pemindaian otomatis, dengan footprint validate sebagai satu-satunya penyaringan.
  • cc-arcade, GitHub, sezaakgun. Mengapa dibaca: demo yang membuat fitur ini terlihat, dan tur $.ui.
  • Boris Cherny announcement tweet, X, Boris Cherny. Mengapa dibaca: pernyataan peluncuran dari seorang engineer Anthropic, karena tidak ada posting blog.
  • Prathkum: Function Hooks explained, X, Prathkum. Mengapa dibaca: penjelasan singkat terbaik tentang hooks vs Mods untuk orang yang sudah menulis shell hook.
  • shipnotesai reaction thread, X, shipnotesai. Mengapa dibaca: tempat klaim "hanya REPL" beredar, yang dibantah oleh pengujian kami.
  • Claude Code Function Hooks: Preview Behind a Flag, claudefa.st. Mengapa dibaca: penjelasan pra-rilis, bagus untuk membandingkan proposal dengan binary.
  • cc-mod-waitwhat, GitHub, GGGODLIN. Mengapa dibaca: Mod kecil yang mudah dibaca dan menulis ke UI, bukan ke transkrip.
  • claude-mods-skill, GitHub, BeLazy167. Mengapa dibaca: skill untuk meng-generate Mod, kalau Anda ingin mengulang eksperimen satu kalimat itu.
  • AxialisSoftware reaction, X, AxialisSoftware. Mengapa dibaca: argumen skeptis, dalam satu tweet.

FAQ

Apakah Mod menggantikan shell hook saya sekarang?

Belum, untuk apa pun yang harus memblokir. Di 2.1.272, hook yang melempar error atau macet lebih dari 10 s akan dilewati dan perintahnya jalan. Shell hook tetap berfungsi, jadi biarkan yang bersifat memblokir di sana sampai ada catch yang dideklarasikan atau opsi fail-closed.

Mengapa validate penting kalau Mod-nya jalan baik-baik saja?

Karena baris hooks: dan calls:-nya adalah satu-satunya tampilan statis tentang apa yang disentuh Mod di $. Untuk Mod Anda sendiri itu mengonfirmasi footprint; untuk Mod pihak ketiga itu seluruh review yang Anda dapat sebelum kodenya berjalan di proses Anda.

Berapa biaya sebuah Mod per sesi?

claude plugin details melaporkan sekitar 0 token tambahan. Mod adalah kode yang berjalan di engine, bukan teks di prompt, dan itu keunggulan utamanya dibanding skill atau aturan CLAUDE.md.

Mengapa Mod termuat di -p tetapi tidak di REPL?

Tidak diketahui. Dua percobaan lewat pty tetap diam sementara claude -p memuat dan menerapkan hook. Penyebab yang paling mungkin adalah lingkungan pty, bukan fiturnya, jadi uji di terminal Anda sendiri sebelum mengandalkan salah satu arah.