FACT — फ़ाइलों का स्वरूप। एक न्यूनतम मॉड तीन फ़ाइलें हैं:
first-mod/
├── .claude-plugin/
│ └── plugin.json
└── hooks/
├── hooks.json # { "modules": ["./register.js"] }
└── register.js # export function register(on) { ... }
hooks/hooks.json में modules कुंजी ठीक वही चीज़ है जो "इस प्लगइन को मॉड बनाती है"।
FACT — तीन आर्ग्युमेंट। $ — मॉड्स एपीआई, नेमस्पेस में बंटी हुई ($.ui, $.fs, $.process, $.http, $.env, $.settings, $.store, $.state, $.clock, $.command, $.tool, $.mcp, $.model, $.session, $.agent, $.prompt, $.telemetry, $.audio, $.config)। e — इवेंट इनपुट, प्लेन और गहराई तक फ़्रोज़न डेटा के रूप में। next — कंटीन्यूएशन (continuation)।
FACT — रनटाइम वातावरण। एक हुक्स मॉड्यूल अपने अलग वातावरण में चलता है: न DOM, न Node, न require, न डायनामिक import()। मॉड्यूल और उनके इम्पोर्ट का नाम .ts .tsx .jsx .js .mjs .cjs .mts .cts में से किसी एक के साथ होना चाहिए और वे ES मॉड्यूल होने चाहिए। सिर्फ़ प्लगइन डायरेक्टरी के भीतर के रिलेटिव इम्पोर्ट allowed हैं, एक बेयर इम्पोर्ट (bare import) की अनुमति है: claude-code। चूंकि एम्बिएंट एक्सेस (ambient access) हटा दिया गया है, एक स्टैटिक स्कैनर $ कॉल्स की गिनती कर सकता है — और ठीक यही चीज़ है जो claude plugin validate छापता है और जो किसी पॉलिसी मॉड के plugin.register जांच को संभव बनाती है।
FACT — मैचर फ़िल्टर (matcher filters)। एक मैचर वह ऑब्जेक्ट है जिसे इवेंट से तुलना की जाती है: कोई मान, अनुमत मानों की सूची, या एक रेगुलर एक्सप्रेशन (on('tool.call', { tool: /^mcp__github__/ }, hook))। वाइल्डकार्ड (wildcard) काम करते हैं: 'classic.*' हर सेटिंग्स-हुक इवेंट से मेल खाता है, '*' टेलीमेट्री इवेंट्स के अलावा हर इवेंट से मेल खाता है।
FACT — इवेंट सरफ़ेस, Anthropic की अपनी जनरेट की गई डिक्लेरेशन से पढ़ा हुआ। claude-code.d.ts में घोषित इंजन इवेंट प्रकार ये हैं (शिप हुए रेपो से प्राप्त; देखें §19):
- टूल्स (Tools):
tool.call, tool.check, tool.register, tool.list, tool.describe
- प्रॉम्प्ट / कॉन्टेक्स्ट:
prompt.submit, prompt.compose, prompt.edit, prompt.fill, prompt.read, prompt.section, prompt.context, prompt.suggest, prompt.attachment, skill.prompt
- टर्न (Turns):
turn.start, turn.step (स्ट्रीमिंग, async जनरेटर के रूप में लिखा गया), turn.complete, turn.abort
- सत्र (Session):
session.start, session.end, session.id, session.cwd, session.root, session.messages, session.usage, session.measure, session.compact, session.attach, session.detach, session.receive, session.send, session.model, session.repo, session.surface, session.surfaces, session.turns, session.version, session.authorize
- इंटरफ़ेस:
ui.render, ui.resolve, ui.press, ui.input, ui.select, ui.focus, ui.open, ui.close, ui.panes, ui.scroll, ui.log, ui.message, ui.notice, ui.toast, ui.status, ui.invalidate, ui.blit
- कमांड / कॉन्फ़िग / प्लगइन:
command.register, command.run, command.list, command.describe, config.list, config.describe, config.set, plugin.register, engine.create
- एजेंट्स (Agents):
agent.spawn, agent.offer, agent.register, agent.list
- एट्रिब्यूशन (Attribution):
attribution.text
- क्लासिक मिरर (Classic mirror):
classic.<SettingsHookEvent> — हर सेटिंग्स-हुक इवेंट मॉड के भीतर से पहुंच-योग्य है
- टेलीमेट्री (Telemetry): अलग, जो
{ to: 'collector' } लेती है
FACT — क्रम का नियम। एक ही इवेंट पर लगे हुक्स एक मिडलवेयर चेन बनाते हैं। "पहला मॉड सबसे बाहरी होता है: वह इवेंट को बाक़ियों से पहले देखता है और नतीजा उनके बाद देखता है, और वह तय करता है कि बाक़ी चलेंगे भी या नहीं।" क्रम यह है: (1) sec-default@builtin, फिर संगठन का prependPlugins, फिर कोई भी दूसरा संगठन मॉड; (2) उपयोगकर्ता द्वारा इंस्टॉल किए गए मॉड्स; (3) संगठन का appendPlugins; (4) दूसरे बिल्ट-इन मॉड्स। किसी एक टियर के भीतर, लोड क्रम; एक मॉड अपनी मैनिफ़ेस्ट (manifest) dependencies से पहले चलता है।
FACT — उस चेन में सेटिंग्स हुक्स ठीक कहां बैठते हैं। मैनेज्ड-सेटिंग्स (managed-settings) के PreToolUse हुक पहले मॉड के tool.call से पहले चलते हैं, और उनका ब्लॉक अंतिम होता है — कोई मॉड वह कॉल देखता ही नहीं। बाक़ी हर सेटिंग्स फ़ाइल और प्लगइन्स से आने वाले PreToolUse हुक आख़िरी मॉड के next कॉल करने के बाद चलते हैं। tool.check उन हुक्स और परमिशन नियमों के फ़ैसला लेने के बाद फायर होता है, इसलिए एक tool.check हुक उस कॉल को मंज़ूर कर सकता है जिसे किसी नॉन-मैनेज्ड PreToolUse हुक ने ब्लॉक किया था।
FACT — विफलता का अर्थशास्त्र। जो हुक थ्रो करता है, टाइम आउट होता है, या गलत आकार लौटाता है, वह सत्र नहीं तोड़ता: अगर उसने next कॉल नहीं किया था, तो Claude Code उसे छोड़ देता है और अगला हैंडलर चलता है; अगर next पहले ही रिज़ॉल्व हो चुका था, तो वह नतीजा बना रहता है। on(...).catch(handler) एक फेल-क्लोज़्ड (fail-closed) हैंडलर जोड़ता है — डॉक्यूमेंट किया गया उपयोग यह है कि किसी ब्लॉकिंग हुक को खुला रहने के बजाय बंद रहने वाला बनाया जाए। किसी $ कॉल के भीतर इंतज़ार में बीता समय (जैसे $.ui.ask) हुक की समय-सीमा में नहीं गिना जाता; मॉड के अपने प्रॉमिस पर बीता समय गिना जाता है।
FACT — एक सख़्त सीमा। "एक मॉड Claude Code के इंटरफ़ेस का बहुत हिस्सा रीस्टाइल कर सकता है, लेकिन परमिशन प्रॉम्प्ट नहीं। वह यह नहीं बदल सकता कि कोई प्रॉम्प्ट आपको क्या दिखाता है।" यह ब्लॉग पोस्ट, ओवरव्यू पेज और एडमिन पेज, तीनों में कहा गया है।
