हुक

हुक टूल इवेंट पर सक्रिय होते हैं और ऐसे संदेश संदर्भ लोड करते हैं जिन्हें सहायक अतिरिक्त सिस्टम प्रॉम्प्ट के रूप में मानता है। वायरिंग Claude Code के settings.json हुक ब्लॉक (इंजन इंस्टॉल) या प्लगइन के hooks.json (प्लगइन इंस्टॉल), Codex की hooks.json हुक फ़ाइल, Qwen Code के settings.json हुक मैप, CodeBuddy की .codebuddy/settings.local.json हुक कुंजी (केवल SessionStart और PostToolUse), Kiro की हुक फ़ाइल .kiro/hooks/apothem.json (केवल SessionStart), GitHub Copilot की हुक फ़ाइल .github/hooks/apothem.json (केवल sessionStart और postToolUse), Windsurf (Devin Local) की .devin/config.local.json हुक कुंजी (केवल SessionStart और PostToolUse), और Cursor की प्रोजेक्ट हुक फ़ाइल .cursor/hooks.json (केवल sessionStart) में रहती है।

डिस्पैचरCopy Anchor Link

इंजन द्वारा इंस्टॉल की गई हुक प्रविष्टियाँ डिस्पैचर को उसके निरपेक्ष स्क्रिप्ट पथ से, इंस्टॉल के समय हल किए गए इंटरप्रेटर के साथ, बुलाती हैं। टेम्पलेट ${PYTHON_BIN} और ${HARNESS_ROOT} टोकन रखते हैं, जिन्हें इंस्टॉलर इंस्टॉल के समय रेंडर करता है। Claude Code और Qwen Code डिस्पैचर को <harness-root>/.apothem/support/hooks/ के अंतर्गत मूर्त रूप देते हैं; Codex <harness-root>/hooks/ के अंतर्गत। Claude Code प्रविष्टियाँ exec रूप (command और args) का उपयोग करती हैं, इसलिए उन्हें किसी शेल की आवश्यकता नहीं होती। Claude Code प्लगइन प्रत्येक हुक को bash "${CLAUDE_PLUGIN_ROOT}/lib/apothem/hooks/lib/bootstrap.sh" <event> [<message-file> ...] के रूप में, Claude Code के डिफ़ॉल्ट हुक शेल (macOS और Linux पर sh, Windows पर Git Bash) में चलाता है; बूटस्ट्रैप एक Python 3.10+ इंटरप्रेटर ढूँढता है और बंडल किए गए डिस्पैचर को चलाता है। यह मिले हुए इंटरप्रेटर को हुक स्थिति डायरेक्टरी (नीचे) के अंतर्गत interpreter-path (bootstrap.ps1 के लिए interpreter-path-ps1) में कैश करता है और जब तक वह इंटरप्रेटर मौजूद रहता है उसका पुनः उपयोग करता है, इसलिए PATH जाँच हर टूल कॉल से पहले नहीं बल्कि एक बार चलती है; नई जाँच बाध्य करने के लिए कैश फ़ाइल हटा दें। केवल निरपेक्ष स्थिति डायरेक्टरी और निरपेक्ष कैश किया गया पथ ही मान्य होते हैं।

हर सतह प्रति इवेंट और मैचर एक डिस्पैचर प्रविष्टि पंजीकृत करती है, जो उन सभी संदेशों को सूचीबद्ध करती है जिनका वह मैचर मूल्यांकन करता है: एक प्रक्रिया पेलोड को एक बार पढ़ती है, हर गार्ड चलाती है, और एक एनवेलप के साथ उत्तर देती है, इसलिए एक Write हर गार्ड के लिए एक नहीं बल्कि एक ही डिस्पैचर शुरू करता है। Claude Code इंजन इंस्टॉल Write और Edit पर अनुरूपता गेट (gate.py --hook) को भी उसकी अपनी प्रविष्टि के रूप में चलाता है। Git for Windows के बिना Windows पर, इंजन इंस्टॉल (apothem install --harness claude-code) का उपयोग करें, जिसके exec-रूप हुक को किसी शेल की आवश्यकता नहीं होती। डिस्पैचर एक स्वतंत्र stdlib स्क्रिप्ट है: यह अपना sys.path स्वयं बूटस्ट्रैप करता है, इसलिए होस्ट पर किसी आयात-योग्य apothem पैकेज की आवश्यकता नहीं होती। किसी स्रोत चेकआउट से, मॉड्यूल रूप python -m apothem.hooks.dispatch <event> (PYTHONPATH=src के साथ) विकास के लिए वही कोड चलाता है। डिस्पैचर इकोसिस्टम-रूट निर्धारण के लिए hooks/lib/resolve_root.py लोड करता है और hooks/emit_hook_context.py तथा hooks/session_start_bootstrap.py को कार्य सौंपता है।

वेंडर अनुबंधCopy Anchor Link

जो हार्नेस Claude Code नहीं है, वह वही डिस्पैचर स्क्रिप्ट के बाद --contract <id> के साथ चलाता है, उदाहरण के लिए "<python>" "<project>/.apothem/support/hooks/dispatch.py" --contract codebuddy SessionStart। अनुबंध (hooks/lib/vendor_contract.py) वेंडर की इवेंट और टूल-नाम वर्तनियों तथा पेलोड कुंजियों को उस Claude आकार में अनुवादित करता है जिसे हैंडलर पढ़ते हैं, एनवेलप को उस आकार में फिर से लिखता है जिसे वेंडर पढ़ता है, और ऐसे इवेंट को छोड़ देता है जिसे वेंडर मॉडल को नहीं सौंपता। फ़्लैग के बिना कुछ भी अनुवादित नहीं होता और आउटपुट बाइट-दर-बाइट Claude एनवेलप होता है। यह फ़्लैग डिस्पैचर की प्रलेखित कमांड लाइन का हिस्सा है: dispatch.py [--contract <id>] <Event> [<message> ...]।

codebuddy, copilot, cursor, devin और kiro अनुबंध आज एक Apothem एडैप्टर द्वारा इंस्टॉल किए जाते हैं (devin Windsurf एडैप्टर द्वारा); claude अनुबंध प्रमाणित करता है कि डिफ़ॉल्ट कमांड लाइन अपरिवर्तित है। डिस्पैचर हर अनुबंध के अंतर्गत सलाहकारी बना रहता है: कोई भी आकार अनुमति, निर्णय, ब्लॉक या फिर से लिखा गया टूल इनपुट नहीं ले जाता।

Cursor और Devin Local अपने हुक के साथ-साथ Claude Code की सेटिंग्स फ़ाइलों में रखे हुक भी लोड करते हैं, इसलिए उसी मशीन पर Apothem Claude Code इंस्टॉल होने पर दो सेट चल सकते हैं। SessionStart बूटस्ट्रैप एक बार पहुँचाया जाता है: वेंडर का अपना कमांड (--contract cursor या --contract devin) और Claude Code प्रति, जो डिफ़ॉल्ट कमांड लाइन है, हुक स्थिति डायरेक्टरी में प्रति सत्र और स्रोत एक मार्कर साझा करते हैं, और जो भी दूसरे क्रम पर चलता है वह मौन रहता है। डिफ़ॉल्ट कमांड लाइन केवल तब भाग लेती है जब प्रक्रिया परिवेश होस्ट का नाम देता है (CURSOR_PROJECT_DIR, CURSOR_VERSION या DEVIN_PROJECT_DIR); Claude Code, Codex और Qwen Code के अंतर्गत यह मार्कर कभी नहीं पढ़ती। मार्कर दस सेकंड के लिए बाँधता है, इसलिए उसी सत्र की बाद की शुरुआत, जैसे दूसरा कॉम्पैक्शन, फिर भी अपना रिकवरी संदर्भ पहुँचाती है। किसी PostToolUse काउंटर का दोहराव नहीं हटाया जाता, इसलिए संदर्भ-आकार काउंटर दोनों जगह चलता है और अपनी सीमाओं तक जल्दी पहुँचता है। इंस्टॉल एक नोट प्रिंट करता है जो आयात बंद करने के लिए वेंडर के स्विच का नाम देता है (Cursor का "Include Third-Party Plugins, Skills, and Other Configs"; Devin का read_config_from.claude)।

कोई कमांड केवल वहीं पंजीकृत होता है जहाँ वेंडर उसका आउटपुट मॉडल को सौंपता है। Kiro किसी हुक का stdout केवल SessionStart और UserPromptSubmit के लिए संदर्भ में जोड़ता है, इसलिए Kiro फ़ाइल केवल SessionStart पंजीकृत करती है। Copilot sessionStart और postToolUse से additionalContext पढ़ता है और preToolUse से केवल अनुमति फ़ील्ड, इसलिए Copilot फ़ाइल वे दो इवेंट, उनके camelCase नामों के अंतर्गत, पंजीकृत करती है और कोई गार्ड नहीं। हर Copilot प्रविष्टि एक bash और एक powershell कमांड रखती है। दोनों फ़ाइलें Apothem-स्वामित्व वाली हैं और उस मशीन के इंटरप्रेटर और प्रोजेक्ट पथ का नाम देती हैं जिसने इंस्टॉल चलाया; हार्नेस पृष्ठ बताते हैं कि किसी रिपॉज़िटरी द्वारा कमिट की गई फ़ाइल के लिए इसका क्या अर्थ है।

Devin Local SessionStart, UserPromptSubmit और PostToolUse से additionalContext पढ़ता है और PreToolUse के लिए ऐसा कुछ प्रलेखित नहीं करता, इसलिए Windsurf पंजीकरण SessionStart और PostToolUse रखता है, बिना मैचर के (Devin का मैचर एक रेगुलर एक्सप्रेशन है, और छोड़ा गया मैचर हर टूल से मेल खाता है)। यह स्थानीय ओवरराइड .devin/config.local.json में जाता है, जिसे Devin gitignored के रूप में प्रलेखित करता है और .git/info/exclude के माध्यम से स्वयं git से बाहर रखता है। Cursor का sessionStart हुक बातचीत के प्रारंभिक संदर्भ में additional_context जोड़ता है; पहला संस्करण केवल वही इवेंट पंजीकृत करता है। Cursor की .cursor/hooks.json एकमात्र प्रोजेक्ट हुक फ़ाइल है, इसलिए यह ऑपरेटर की है: इंस्टॉल उसमें एक प्रविष्टि मर्ज करता है, ऑपरेटर की प्रविष्टियाँ और कुंजियाँ रखता है, ऐसी फ़ाइल को अस्वीकार करता है जिसे वह बिना हानि के फिर से नहीं लिख सकता, और कमांड में डिस्पैचर पथ से अपनी प्रविष्टि को पहचानता है। Cursor का डेस्कटॉप ऐप Windows पर हुक कमांड PowerShell के माध्यम से चलाता है, इसलिए Windows होस्ट पर कमांड & से शुरू होता है।

सभी पाँच फ़ाइलों में कोई प्रविष्टि Apothem की तब होती है जब उसका कमांड --contract <id> के साथ .apothem/support/[<harness>/]hooks/dispatch.py चलाता है, चाहे वह किसी भी प्रोजेक्ट पथ के अंतर्गत लिखी गई हो। इसलिए नाम बदला गया, स्थानांतरित या क्लोन किया गया प्रोजेक्ट प्रविष्टियों का एक ही सेट रखता है, और आपका कोई हुक, जैसे आपके अपने ट्री में hooks/dispatch.py या python -m apothem.conformity.gate, कभी बदला या हटाया नहीं जाता। जब फ़ाइल में Apothem की कोई प्रविष्टि नहीं बचती तो apothem verify पंजीकरण को अनुपस्थित रिपोर्ट करता है, और जो अनइंस्टॉल फ़ाइल नहीं पढ़ सकता वह उसे छोड़ा गया रिपोर्ट करता है। जिस प्रोजेक्ट या इंटरप्रेटर पथ में $, बैकटिक, डबल कोट या बैकस्लैश हो, उसे इंस्टॉल के समय पथ का नाम देते हुए अस्वीकार कर दिया जाता है, क्योंकि उद्धृत कमांड कोई दूसरी फ़ाइल चलाएगा।

संदेश संदर्भCopy Anchor Link

प्रति-इवेंट Markdown संदर्भ src/apothem/hooks/messages/ के अंतर्गत रहते हैं:

• सत्र जीवनचक्र: sessionstart.md, skill-index.md, precompact.md, postcompact.md, stop.md, posttooluse-proactive-compaction.md
• शेल कॉल: pretooluse-bash.md, pretooluse-bash-plan-guard.md
• फ़ाइल लेखन: pretooluse-write.md, pretooluse-edit.md, pretooluse-notebookedit.md, pretooluse-write-plan-guard.md, pretooluse-write-header-guard.md, pretooluse-edit-header-guard.md, pretooluse-conformity.md
• सामग्री पर गार्ड: pretooluse-dependency-guard.md, pretooluse-eval-guard.md
• प्रश्न: pretooluse-askuserquestion-recommended.md

Claude Code पर, postcompact.md को SessionStart हुक तब पहुँचाता है जब सत्र कॉम्पैक्शन के बाद फिर से शुरू होता है, क्योंकि Claude Code PreCompact या PostCompact हुक आउटपुट को सहायक तक नहीं पहुँचाता।

skill-index.md जनित है, लिखा हुआ नहीं: scripts/dev/generate_skill_index.py इसे स्किल और कमांड कैटलॉग से रेंडर करता है, प्रति कार्य समूह एक पंक्ति, जिसमें मैनुअल स्किल /apothem:<name> के रूप में दिखाए जाते हैं। Claude Code पर SessionStart हुक फ़ाइल मौजूद होने पर इसे सत्र संदर्भ में जोड़ता है। यह इसलिए मौजूद है क्योंकि Claude Code अपनी सूची के वर्ण बजट से बड़ी हो जाने पर उस सूची से स्किल विवरण हटा देता है, और इंडेक्स हर स्किल को कार्य के आधार पर खोजने योग्य रखता है। प्लगइन इंस्टॉल मैनुअल स्किल को /apothem:<name> के रूप में दिखाता है; इंजन इंस्टॉल उपसर्ग हटा देता है। पाठ 1,600 वर्णों से कम रहता है, और generate_skill_index.py --check तब विफल होता है जब कमिट की गई फ़ाइल अब कैटलॉग से मेल नहीं खाती।

जब Apothem केवल Claude Code प्लगइन के रूप में चलता है, तो लॉन्च पर कोई नियम फ़ाइल लोड नहीं होती। तब SessionStart हुक बंडल की गई rules/ डायरेक्टरी का एक छोटा संकेतक जोड़ता है। यदि उस डायरेक्टरी में apothem-rule-index.md है, तो संकेतक सत्र को पहले चार मूल नियम पढ़ने के लिए भी कहता है, क्योंकि इस स्थिति में उन्हें कुछ भी लोड नहीं करता (agnostic-posture, authority-inquiry, session-closure, context-management), और इंडेक्स का नाम देता है, जो बताता है कि किस कार्य के लिए कौन सा नियम पढ़ना है। इंडेक्स का पाठ इनलाइन नहीं किया जाता।

जब प्रोजेक्ट में knowledge-wiki स्किल द्वारा बनाया गया नॉलेज बेस होता है, तो SessionStart हुक उसके फ़िंगरप्रिंट की तुलना पिछली बेसलाइन पर दर्ज फ़िंगरप्रिंट से करता है और, यदि वे भिन्न हों, तो एक पंक्ति जोड़ता है जो स्किल के ड्रिफ़्ट मोड (--mode drift --kb <path>) का सुझाव देती है। फ़िंगरप्रिंट पृष्ठ संख्या और सबसे नई लॉग प्रविष्टि है; दर्ज प्रति बेस के log.md में सबसे नई baseline पंक्ति है, जिसे केवल ड्रिफ़्ट मोड लिखता है। हुक प्रोजेक्ट रूट के अंतर्गत चार पथ, क्रम में, देखता है: knowledge-base/, wiki/, docs/knowledge-base/ और docs/wiki/, और केवल ऐसी डायरेक्टरी जिसमें index.md और log.md दोनों हों। बिना नॉलेज बेस वाला प्रोजेक्ट एक मिलीसेकंड से कम खर्च करता है। उसके साथ, हुक log.md के अधिकतम अंतिम 256 KiB पढ़ता है और तीन सपाट डायरेक्टरी सूचीबद्ध करता है; यह कभी ट्री में नहीं घूमता और कभी नहीं लिखता। पंक्ति में एक निश्चित पथ, एक तारीख और दो पृष्ठ संख्याएँ होती हैं, बेस का कोई पाठ कभी नहीं। यह तब मौन रहता है जब कोई बेस, कोई बेसलाइन, कोई परिवर्तन न हो, या कोई फ़ाइल वह पढ़ न सके, और यह हर सत्र में तब तक दोहराई जाती है जब तक ड्रिफ़्ट मोड नई बेसलाइन दर्ज नहीं करता। किसी अन्य पथ पर स्थित बेस हर स्किल मोड में काम करता है लेकिन उसे कोई सत्र-आरंभ पंक्ति नहीं मिलती।

प्रत्येक संदर्भ फ़ाइल को डिस्पैचर तब लोड करता है जब उसका इवेंट सक्रिय होता है और उसका संदर्भ आर्गुमेंट सेटिंग्स फ़ाइल में पंजीकृत होता है। पाठ के सहायक तक पहुँचने से पहले लाइसेंस टिप्पणी पंक्ति और समापन ## Bindings अनुभाग हटा दिए जाते हैं; दोनों अनुरक्षकों और अनुरूपता गेट के लिए मौजूद हैं।

जो गार्ड कुछ नहीं पाता वह कुछ भी नहीं डालता। जो गार्ड सक्रिय होता है वह अपने संदेश का केवल ## Advisory अनुभाग डालता है, जो उसे मिली चीज़ों (पथ, पहचानकर्ता, प्रिमिटिव) से भरा होता है, और उसके बाद Full procedure: <message-file> आता है। फ़ाइल का शेष भाग पूर्ण प्रक्रिया है, जिसे सहायक केवल तब पढ़ता है जब उसे विवरण की आवश्यकता हो। गार्ड "प्रोजेक्ट के अंदर" का निर्णय टूल कॉल की कार्यशील डायरेक्टरी के ऊपर स्थित git रूट के सापेक्ष करते हैं, उस ट्री के सापेक्ष कभी नहीं जिसमें हुक इंस्टॉल है।

रनटाइम अनुबंधCopy Anchor Link

हर पंजीकृत हुक कमांड एक ही अनुबंध पूरा करता है, जिसकी जाँच tests/hooks/test_hook_contract.py प्लगइन, Claude Code इंजन इंस्टॉल, Codex, Qwen Code, और CodeBuddy इंस्टॉल पर करता है (Kiro, Copilot, Cursor और Windsurf फ़ाइलों की जाँच उनके अनुबंधों के विरुद्ध tests/hooks/test_native_hook_registrations.py करता है, और उन्हें वैसे ही चलाते हैं जैसे वेंडर चलाते हैं tests/integration/test_native_hook_files_roundtrip.py, test_cursor_hooks_roundtrip.py और test_windsurf_hooks_roundtrip.py):

• सादे चेकआउट से चलता है। एग्ज़िट 0, और मानक आउटपुट खाली या एक JSON ऑब्जेक्ट होता है। कोई भी हुक किसी फ़ाइल के निष्पादन-योग्य बिट पर निर्भर नहीं करता।
• एक बार पंजीकृत। प्रत्येक इवेंट और मैचर की प्रति सतह एक डिस्पैचर प्रविष्टि होती है, जो उन सभी संदेशों को सूचीबद्ध करती है जिनका वह मूल्यांकन करती है, इसलिए कोई गार्ड एक टूल कॉल पर कभी दो बार नहीं चलता।
• सीमित। कोई भी उत्सर्जित पाठ 10,000 वर्णों से अधिक नहीं होता। निर्भरता गार्ड केवल तब बोलता है जब कोई लेखन किसी निर्भरता मैनिफ़ेस्ट या लॉकफ़ाइल को लक्षित करता है, और डायनेमिक-eval गार्ड केवल तब जब सामग्री या कमांड में कोई मूल्यांकन या असुरक्षित-डीसीरियलाइज़ेशन प्रिमिटिव हो। कॉम्पैक्शन सलाह प्रति कॉम्पैक्शन चक्र अधिकतम दो बार सक्रिय होती है।
• उन्हीं चैनलों का उपयोग करता है जिन्हें हार्नेस पहुँचाता है। PreToolUse मार्गदर्शन hookSpecificOutput में जाता है; AskUserQuestion गार्ड additionalContext लौटाता है, या सख़्त ऑप्ट-इन के अंतर्गत permissionDecision: deny। Claude Code PreCompact और PostCompact आउटपुट को त्याग देता है, इसलिए Claude Code पर कॉम्पैक्शन-पश्चात रिकवरी संदर्भ उस SessionStart इवेंट के साथ आता है जिसका स्रोत compact है।
• कभी प्रोजेक्ट कोड नहीं चलाता। बूटस्ट्रैप अपने स्वयं के इंस्टॉल किए गए ट्री को हल करता है और खोले गए प्रोजेक्ट से कभी कोई स्क्रिप्ट नहीं लेता। सत्र-आरंभ मार्गदर्शन इंस्टॉल किए गए ट्री से पढ़ा जाता है; प्रोजेक्ट डायरेक्टरी केवल प्लान और मेमोरी सारांशों तथा नॉलेज-बेस ड्रिफ़्ट जाँच के लिए पढ़ी जाती है।
• विफलता में खुला रहता है। अनुपस्थित संदेश फ़ाइल, अनुपस्थित इंटरप्रेटर, या दूषित स्थिति का परिणाम एग्ज़िट 0 और एक वैध एनवेलप होता है।

कॉम्पैक्शन सलाह सत्र ट्रांसक्रिप्ट में सबसे नए उपयोग रिकॉर्ड (इनपुट और कैश किए गए टोकन) से संदर्भ को मापती है, इसलिए यह दर्शाती है कि मॉडल वास्तव में क्या रखता है। उस आकार में तेज़ गिरावट एक कॉम्पैक्शन को चिह्नित करती है और दो-सलाह बजट को फिर से शुरू करती है। जहाँ कोई ट्रांसक्रिप्ट उपलब्ध नहीं है, वहाँ यह इसके बजाय टूल कॉल और आउटपुट बाइट गिनती है।

प्रति-सत्र हुक स्थिति एक प्रति-उपयोगकर्ता डायरेक्टरी में रहती है जो मोड 0700 के साथ बनाई जाती है: सेट होने पर APOTHEM_HOOK_STATE_DIR, अन्यथा Claude Code प्लगइन के लिए ${CLAUDE_PLUGIN_DATA}/state, अन्यथा $XDG_STATE_HOME/apothem, अन्यथा ~/.local/state/apothem (Windows पर %LOCALAPPDATA%\apothem\state)।

जनित हुक संदेश इन्वेंट्रीCopy Anchor Link