Claude Code Mods: fail-open प्रयोग, माप, चेकलिस्ट और स्रोत

TL;DR

• Claude Code Mod तीन फ़ाइलों से बनता है: .claude-plugin/plugin.json, hooks/hooks.json जिसमें {"modules":["./index.ts"]} हो, और एक TypeScript मॉड्यूल जो register(on) export करे। लोड होने के लिए इसके अलावा कुछ नहीं चाहिए।
• build 2.1.272 पर /plugin-types जो typed surface लिखता है वह claude-code.d.ts की 11,783 लाइनें है: 23 nouns पर 84 event या call नाम। fs.readFile अब नहीं है, noun fs.read और fs.write है।
• 42 लाइन के एक tool.call hook ने मॉडल को असली key की जगह API_KEY=[REDACTED] पढ़वाया, Read और Bash दोनों tool पर, हर सामान्य hop 27.9 ms में और सेशन में लगभग 0 token जोड़कर।
• जो hook 10 s budget से ज़्यादा सोता है या throw करता है उसे skip कर दिया जाता है और उसके नीचे का कमांड चल जाता है। log यह बताता है, पर असर bypass का है: guard Mod fail open होता है।
• generate वाला रास्ता काम करता है: एक वाक्य से लगभग 4 मिनट और $1.23 में 190 लाइन का Mod और 53 लाइन के tests बने, claude plugin validate बिना warning के पास हुआ और claude plugin test 4 pass / 0 fail आया।
• एक चीज़ दोबारा नहीं दिखी: Mod claude -p में लोड हुआ पर pty से चलाए गए interactive REPL में दो कोशिशों में चुप रहा। असली terminal पर test करने तक REPL में लोडिंग को unverified मानिए।

मापों से क्या निकला

नीचे सब कुछ Claude Code 2.1.272 पर CLAUDE_CODE_ENABLE_FUNCTION_HOOKS सेट करके चलाया गया, हाथ से लिखे redact-secrets नाम के Mod पर और उसे तोड़ने के लिए बनाए तीन throwaway Mods पर। यह फ़ीचर Function Hooks proposal issue में ट्रैक होता है, जो अब भी आधिकारिक spec के सबसे नज़दीक है s3।

टूलिंग docs से पहले मौजूद है। build 2.1.272 में claude plugin validate, test, eval और details हैं; test तब भी काम करता है जब plugin --help उसे कमांड ब्लॉक में नहीं दिखाता s3। सेशन में /plugin-types चलाने पर .claude/types/claude-code.d.ts में 11,783 लाइनें लिखी गईं, साथ में 3,438 लाइन की claude-code-mcp.d.ts, जो 7 servers के 150 MCP tools को कवर करती है s3। generated types गिनने पर 23 nouns में फैले 84 event या call नाम मिलते हैं, और फ़ाइल एक ऐसी चीज़ का नाम बदलती है जो आपने सितंबर की पोस्ट्स में पढ़ी होगी: fs.readFile अब मौजूद नहीं, surface fs.read और fs.write है s9। यही types बताते हैं कि tool.call hook { result, context? } या { deny } लौटाता है; text और ref core से आते हैं और hook के अपने जवाब का हिस्सा नहीं हैं, इसलिए आप result को rewrite करते हैं, text को नहीं s3।

claude plugin validate Mod के चलने से पहले ही footprint छापता है: ./index.ts hooks: tool.call और ./index.ts calls: $.ui.toast, या calls: nothing on $ अगर मॉड्यूल किसी host capability को नहीं छूता s4। awesome-claude-code-mods जैसी directory आज जो एकमात्र vetting automate कर सकती है वह यही static लाइन है, और अगला पैराग्राफ पढ़ते समय यह मायने रखता है।

redaction -p मोड में काम करता है। 42 लाइन के hook ने tool.call को intercept किया, और जहाँ फ़ाइल और shell output में sk-test1234567890abcdef था वहाँ मॉडल को API_KEY=[REDACTED] मिला, Read tool और Bash tool दोनों के लिए s3। debug log ने एक सामान्य hop को 27.9 ms round trip में दर्ज किया, worker hop और next() समेत s3। claude plugin details ने Mod की कीमत हर सेशन में लगभग 0 token आँकी: Mod प्रोसेस के अंदर का कोड है, prompt का टेक्स्ट नहीं, और shell hooks तथा skills के खिलाफ इसके समर्थकों की मुख्य दलील यही है s7।

guard fail open होता है। 15 s सोने वाले slow-guard Mod को 10 s budget पर काट दिया गया, संदेश hook failed: slow-guard: exceeded 10000ms budget (tool.call; skipped; what is below it ran in its place) के साथ, और echo hi फिर भी चला s3। throw करने वाला throw-guard Mod उसी तरह skip हुआ, hook failed: throw-guard: boom (tool.call; skipped; what is below it ran in its place), 574.2 ms में रिपोर्ट हुआ s3। log में शोर, असर में bypass। जिस भी Mod का काम कुछ रोकना है उसे इसी नज़र से पढ़िए: guard का bug छेद है, crash नहीं।

generate करना सस्ता है। एक वाक्य से मॉडल ने लगभग 4 मिनट, 34 turns और $1.23 में 190 लाइन का काम करने वाला Mod और 53 लाइन के tests लिखे (19,053 output tokens, 497,282 cache-read, 8,357 thinking) s3। वह Mod claude plugin validate में बिना warning और claude plugin test में 0.31 s में 4 pass / 0 fail के साथ पास हुआ, और keys को live छिपाया s3। हाथ से लिखे Mod पर claude plugin test बिना API key और बिना model call के चला: 0.25 s में 1 pass s3। agents को Mods लिखना सिखाने वाली एक skill पहले से मौजूद है, अगर आप template के साथ यह प्रयोग दोहराना चाहें s12।

जो दोबारा नहीं दिखा: $.ui.toast कभी render नहीं हुआ क्योंकि Mod pty से चलाए REPL में 2 कोशिशों में लोड नहीं हुआ; -p में उसका समकक्ष सिर्फ़ एक debug लाइन के रूप में दिखा। X पर घूम रहे "सिर्फ़ REPL" वाले दावे का उल्टा देखा गया, और मूल कारण अलग से नहीं पकड़ा गया s8। अटके हुए worker का 5 s heartbeat भी test नहीं हुआ; सिर्फ़ 10 s await budget और throw वाला रास्ता मापा गया।

माप

Protocol: Claude Code 2.1.272, function hooks environment variable से चालू। हर Mod एक plugin directory है जिसमें plugin.json, hooks/hooks.json और एक index.ts है। रन claude -p से हुए, debug logging चालू रखकर; रखी गई फ़ाइल और shell कमांड दोनों में sk-test1234567890abcdef था। fail-open केस ऐसे Mod से चलाए गए जो 15 s सोता है और ऐसे Mod से जो throw करता है, guard के नीचे का कमांड echo hi था। interactive REPL pty से चलाया गया और दो कोशिशों में Mod लोड नहीं हुआ।

सोमवार को यह करें

• किसी सेशन में /plugin-types चलाएँ और .claude/types/claude-code.d.ts खोलें: सितंबर की किसी भी पोस्ट के snippet पर भरोसा करने से पहले fs.read और tool.call खोजें।
• तीन फ़ाइलों का Mod skeleton लिखें (plugin.json, {"modules":["./index.ts"]} वाला hooks/hooks.json, और register(on) export करने वाला index.ts) और उस पर claude plugin validate चलाएँ: hooks: और calls: footprint लाइनें पढ़ें।
• अपना सबसे ज़्यादा इस्तेमाल होने वाला shell hook एक tool.call handler में port करें जो result rewrite करे, फिर debug log का hop समय shell version से मिलाएँ।
• Mod के बगल में एक claude plugin test फ़ाइल जोड़ें ताकि guard CI में बिना API key के चले।
• हर guard handler को ऐसे try/catch में लपेटें जो failure पर { deny } लौटाए: इस build पर exception या 10 s का stall आपको skip कर देता है और कमांड को निकल जाने देता है।
• Mod को claude -p में और अपने असली interactive terminal में अलग-अलग test करें, और लिख लें कि किसने उसे लोड किया।
• किसी third-party Mod को इंस्टॉल करने से पहले उस पर claude plugin validate चलाएँ और ऐसा हर Mod ठुकरा दें जिसकी calls: लाइन में ऐसी host capabilities हों जिनका उसे इस्तेमाल करने का कोई कारण नहीं।

आगे पढ़ें

• proposal issue को शुरू से अंत तक पढ़ें, कमेंट्स में लगे architecture PDF समेत: register(on), budgets और worker hop के लिए यही एकमात्र लिखित contract है s3।
• Command Code Mods के डिज़ाइन से तुलना करें, जो host प्रोसेस में ModApi के सामने TypeScript चलाता है: दोनों सिस्टम का ढाँचा और early-access gating एक जैसे हैं s2।
• claudefa.st का preview तब लिखा गया जब फ़ीचर सिर्फ़ proposal था: 3 Sep के टेक्स्ट और 2.1.272 binary के बीच क्या बदला यह देखने के काम का है s9।
• Prathkum का note tweet इसका सबसे साफ़ छोटा बयान है कि tokens और latency में in-process hooks shell hooks से क्यों बेहतर हैं s7।
• cc-mod-waitwhat पढ़ने के लिए अच्छा पहला Mod है: prompt के ऊपर UI, transcript में कुछ नहीं लिखा जाता s11।
• cc-arcade दिखाता है कि $.ui कितनी दूर तक पहुँचता है: Mod से prompt के ऊपर render होते games s5।
• hooks reference अब भी shell model का वर्णन करता है; इसे खुला रखिए ताकि हर पुराने event को उसके नए noun.event नाम से मिला सकें s1।
• X पर संशयवादी कहते हैं कि plugins यह सब पहले से कवर करते हैं और surface हर release में टूटेगा; नाम बदला हुआ fs noun उनके लिए एक data point है s23।

स्रोत

• Function Hooks proposal (issue #91870), GitHub, anthropics/claude-code. क्यों पढ़ें: Mods के लिए spec जैसा एकमात्र टेक्स्ट, architecture PDF और कमेंट्स में shipping trail के साथ।
• Hooks reference, Claude Code docs. क्यों पढ़ें: जिस shell-hook मॉडल से आप migrate कर रहे हैं, event दर event।
• Command Code Mods documentation, Command Code. क्यों पढ़ें: उसी TypeScript-in-process ढाँचे वाला prior art, यह देखने के लिए कि Anthropic ने क्या अपनाया या टाला।
• awesome-claude-code-mods, GitHub, karanb192. क्यों पढ़ें: public Mods की auto-scanned directory, जिसकी एकमात्र vetting validate footprint है।
• cc-arcade, GitHub, sezaakgun. क्यों पढ़ें: वह demo जिसने फ़ीचर को दिखाया, और $.ui का दौरा।
• Boris Cherny announcement tweet, X, Boris Cherny. क्यों पढ़ें: Anthropic के एक engineer का launch बयान, क्योंकि कोई blog पोस्ट नहीं है।
• Prathkum: Function Hooks explained, X, Prathkum. क्यों पढ़ें: जो पहले से shell hooks लिखता है उसके लिए hooks बनाम Mods की सबसे अच्छी छोटी व्याख्या।
• shipnotesai reaction thread, X, shipnotesai. क्यों पढ़ें: जहाँ "सिर्फ़ REPL" वाला दावा घूमा, जिसे हमारे रन ने गलत पाया।
• Claude Code Function Hooks: Preview Behind a Flag, claudefa.st. क्यों पढ़ें: ship से पहले की व्याख्या, proposal और binary का फ़र्क देखने के लिए अच्छी।
• cc-mod-waitwhat, GitHub, GGGODLIN. क्यों पढ़ें: एक छोटा पढ़ने लायक Mod जो transcript में नहीं, UI में लिखता है।
• claude-mods-skill, GitHub, BeLazy167. क्यों पढ़ें: Mods generate करने की skill, अगर आप एक वाक्य वाला प्रयोग दोहराना चाहें।
• AxialisSoftware reaction, X, AxialisSoftware. क्यों पढ़ें: संशयवादी पक्ष, एक tweet में।

FAQ

क्या Mod आज मेरे shell hooks की जगह लेता है?

उन चीज़ों के लिए नहीं जिन्हें रोकना ज़रूरी है। 2.1.272 पर जो hook throw करता है या 10 s से ज़्यादा अटकता है उसे skip कर दिया जाता है और कमांड चल जाता है। shell hooks काम करते रहते हैं, इसलिए declared catch या fail-closed विकल्प आने तक रोकने वाले hooks वहीं रखिए।

Mod ठीक चल रहा हो तो validate क्यों मायने रखता है?

क्योंकि उसकी hooks: और calls: लाइनें इस बात का एकमात्र static दृश्य हैं कि Mod $ पर क्या छूता है। अपने Mod के लिए यह footprint की पुष्टि करता है; third-party Mod के लिए कोड आपके प्रोसेस में चलने से पहले यही पूरा review मिलता है।

एक Mod की प्रति सेशन कितनी लागत है?

claude plugin details ने लगभग 0 token जुड़ना बताया। Mod इंजन में चलने वाला कोड है, prompt में टेक्स्ट नहीं, और skill या CLAUDE.md नियम पर इसका मुख्य फ़ायदा यही है।

Mod -p में लोड हुआ पर REPL में क्यों नहीं?

पता नहीं। pty से की गई दो कोशिशें चुप रहीं जबकि claude -p ने hook लोड करके लागू किया। संभावित कारण फ़ीचर नहीं बल्कि pty का environment है, इसलिए किसी भी दिशा पर भरोसा करने से पहले अपने terminal पर test करें।