settings.json दस्तावेज़ीकरण

दायरा। यह दस्तावेज़ Claude Code एडॉप्टर की हुक वायरिंग फ़ाइल (settings.json) का वर्णन करता है। अन्य harness अपने स्वयं के नेटिव सेटिंग्स सरफ़ेस का उपयोग करते हैं — प्रत्येक एडॉप्टर के समतुल्य कॉन्फ़िगरेशन एंट्री पॉइंट के लिए site/content/docs/harnesses/<harness>.mdx देखें।

अवलोकन

settings.json Apothem इकोसिस्टम के लिए Claude Code हुक निष्पादन को कॉन्फ़िगर करती है। यह घोषित करती है कि कौन-से हुक किन इवेंट पर चलते हैं, उनके टाइमआउट, और शीर्ष-स्तरीय अनुमति सरफ़ेस। Apothem एक ही कैनोनिकल टेम्पलेट भेजता है क्योंकि Claude Code सभी समर्थित प्लेटफ़ॉर्म पर ~/.claude/settings.json लोड करता है।

केवल-Python रनटाइम

प्रत्येक कॉन्फ़िगर किया गया हुक Claude Code की exec-फ़ॉर्म कमांड संरचना का उपयोग करता है। भेजा गया टेम्पलेट ${HARNESS_ROOT} टोकन रखता है:

{
  "type": "command",
  "command": "python",
  "args": ["${HARNESS_ROOT}/apothem/hooks/dispatch.py", "PreToolUse", "pretooluse-write"]
}

apothem install इस टोकन को harness रूट के निरपेक्ष पथ (फ़ॉरवर्ड-स्लैश फ़ॉर्म, Windows, macOS और Linux पर मान्य) के रूप में रेंडर करता है, ताकि स्थापित settings.json ~/.claude/.apothem/support/hooks/dispatch.py पर मटीरियलाइज़ किए गए डिस्पैचर को सीधे आह्वान करे। डिस्पैचर और कॉन्फ़ॉर्मिटी गेट (~/.claude/.apothem/support/conformity/gate.py, जिसके schema फ़िक्स्चर इसके बगल में ~/.claude/.apothem/support/schemas/ पर हैं) दोनों स्टैंडर्ड-लाइब्रेरी के स्वतंत्र स्क्रिप्ट हैं — होस्ट पर किसी इम्पोर्ट-योग्य apothem पैकेज की आवश्यकता नहीं है, और एक ही टेम्पलेट प्रत्येक प्लेटफ़ॉर्म की सेवा करता है।

हुक कॉन्फ़िगरेशन Schema

अनुमतियाँ

"permissions": {
  "allow": ["Read", "Glob", "Grep"]
}

allow में नहीं आने वाले टूल को स्पष्ट प्रति-कॉल अनुमोदन या वर्कस्पेस-स्तरीय अनुमति की आवश्यकता होती है। केवल-पढ़ने वाले टूल पूर्व-अनुमोदित हैं; लेखन संचालन (Write, Edit, NotebookEdit, Bash) PreToolUse वैलिडेटर से होकर चलते हैं।

हुक इवेंट

टाइमआउट मान कैनोनिकल हुक-इवेंट बजट को प्रतिबिंबित करते हैं — नीचे दी गई तालिका पाठक की सुविधा के लिए उन्हें पुनः प्रस्तुत करती है; कैनोनिकल स्रोत मान्य रहता है।

dispatch.py अपनी इवेंट व्हाइटलिस्ट पर अतिरिक्त रूप से UserPromptSubmit और Notification को स्वीकार करता है। भेजे गए टेम्पलेट में दोनों में से कोई वायर नहीं किया गया है; इसे सक्षम करने के लिए उसी लोकेटर + डिस्पैच पैटर्न के साथ एक matcher ब्लॉक जोड़ें।

शीर्ष-स्तरीय फ़ील्ड

सत्यापन

तीन वैलिडेटर बढ़ती कठोरता के साथ हुक सरफ़ेस को कवर करते हैं:

# संरचनात्मक + Python स्वच्छता (तेज़, ऑफ़लाइन)
python scripts/dev/validate_hooks.py

# पूर्ण इकोसिस्टम (संरचना + frontmatter + प्रत्यायोजित हुक जाँच)
python scripts/dev/validate_ecosystem.py

# प्रतिकूल स्वीप (प्रत्येक कॉन्फ़िगर किए गए हुक कमांड पर अवक्रमित इनपुट से प्रहार करता है)
python scripts/dev/chaos_pass.py

हुक या सेटिंग्स परिवर्तन कमिट करने से पहले तीनों को 0 के साथ निकलना चाहिए।

किसी एकल इवेंट का तदर्थ स्मोक टेस्ट:

python src/apothem/hooks/dispatch.py --event-name SessionStart

अपेक्षित आउटपुट: hookSpecificOutput वाला एकल-पंक्ति JSON लिफ़ाफ़ा।

सामान्य समस्याएँ

SessionStart टाइमआउट हो जाता है

सबसे आम तौर पर find-python लोकेटर Microsoft Store शिम खोज रहा होता है और एक वास्तविक इंटरप्रेटर हल करने में विफल हो रहा होता है। सत्यापित करें:

python src/apothem/hooks/dispatch.py --event-name SessionStart

यदि कमांड एक वैध JSON लिफ़ाफ़ा प्रिंट करता है लेकिन Claude Code पैनल टाइमआउट दिखाता है, तो settings.json में इवेंट के timeout को बढ़ाएँ। यदि कमांड शेल स्तर पर विफल होता है, तो एक वास्तविक CPython 3.10+ स्थापित करें और सुनिश्चित करें कि यह PATH पर है या लोकेटर द्वारा खोज-योग्य है।

प्रत्येक Write/Edit अवरुद्ध है

PreToolUse harness इंस्टॉल रूट (Claude Code एडॉप्टर के लिए ~/.claude/) के बाहर लिखी जा रही सामग्री में प्लान-आंतरिक शब्दों को फ़्लैग कर रहा है। सामग्री में CM-7 उल्लंघनों के लिए समीक्षा करें (देखें src/apothem/rules/persistent-conventions-vigilance.md)। कोडबेस आर्टिफ़ैक्ट के लिए केवल डोमेन भाषा।

settings.json लोड नहीं हुई

Claude Code ~/.claude/settings.json पढ़ता है। सत्यापित करें कि Apothem अपेक्षित harness रूट में स्थापित हुआ है और फ़ाइल बदलने के बाद सत्र को पुनः आरंभ करें।

हुक चुपचाप no-op होते हैं

हुक अनुबंध है "हमेशा 0 के साथ निकलें, हमेशा वैध JSON उत्सर्जित करें"। यदि इंटरप्रेटर का पता नहीं लगाया जा सकता तो लोकेटर खाली लौटाता है और कमांड no-op बन जाता है। यह पुष्टि करने के लिए chaos_pass.py चलाएँ कि प्रत्येक कॉन्फ़िगर किया गया हुक एक वैध लिफ़ाफ़ा लौटाता है — यह अवक्रमित समाधान पथों को पकड़ लेता है जिन्हें एक लाइव सत्र छिपा देगा।

स्तरित प्राथमिकता

Claude Code बढ़ती प्राथमिकता के क्रम में तीन परतों को संयोजित करके प्रभावी सेटिंग्स ऑब्जेक्ट को हल करता है:

उच्च-स्तरीय मान निम्न-स्तरीय मानों को लीफ़-की स्तर पर ओवरराइड करते हैं — जब प्रोजेक्ट और उपयोगकर्ता-लोकल दोनों परतें एक permissions.allow प्रविष्टि घोषित करती हैं, तो संघ लिया जाता है; जब दोनों theme जैसा कोई स्केलर घोषित करती हैं, तो उपयोगकर्ता-लोकल मान जीतता है। सटीक प्रति-की मर्ज सिमैंटिक्स का स्वामित्व Claude Code harness के पास है।

उपयोगकर्ता-लोकल ओवरराइड बनाना

1. settings.local.example.json (रिपॉज़िटरी रूट) को <harness-root>/settings.local.json में कॉपी करें। settings.local.json फ़ाइलनाम .gitignore पैटर्न से मेल खाता है, इसलिए फ़ाइल कभी संस्करण नियंत्रण में नहीं उतरती।
2. लोकल कॉपी संपादित करें — केवल ओवरराइड करने वाली की रखें; harness परतों को संयोजित करता है, इसलिए अनुपस्थित की प्रोजेक्ट परत से उत्तराधिकार में मिलती हैं।
3. सहेजने से पहले सत्यापित करें कि फ़ाइल वैध JSON के रूप में पार्स होती है — harness सत्र आरंभ पर विकृत JSON को अस्वीकार करता है।