Architecture

​

title: आर्किटेक्चर description: “हुक हैंडलर, कॉन्फ़िग लोडिंग, और पॉलिसी मूल्यांकन कैसे काम करते हैं” icon: sitemap

यह दस्तावेज़ बताता है कि failproofai आंतरिक रूप से कैसे काम करता है: हुक सिस्टम एजेंट टूल कॉल को कैसे इंटरसेप्ट करता है, कॉन्फ़िग कैसे लोड और मर्ज होता है, पॉलिसीज़ का मूल्यांकन कैसे होता है, और डैशबोर्ड एजेंट गतिविधि की निगरानी कैसे करता है।

---

​

अवलोकन

failproofai के दो स्वतंत्र सबसिस्टम हैं:

1. हुक हैंडलर - एक तेज़ CLI सबप्रोसेस जो Claude Code हर एजेंट टूल कॉल पर चलाता है। पॉलिसीज़ का मूल्यांकन करता है और एक निर्णय देता है।
2. एजेंट मॉनिटर (डैशबोर्ड) - एजेंट सेशन की निगरानी और पॉलिसीज़ को प्रबंधित करने के लिए एक Next.js वेब एप्लिकेशन।

दोनों सबसिस्टम ~/.failproofai/ और प्रोजेक्ट की .failproofai/ डायरेक्टरी में कॉन्फ़िग फ़ाइलें साझा करते हैं, लेकिन वे अलग-अलग प्रक्रियाओं के रूप में चलते हैं और केवल फ़ाइलसिस्टम के माध्यम से संचार करते हैं।

---

​

हुक हैंडलर

​

Claude Code के साथ एकीकरण

जब आप failproofai policies --install चलाते हैं, तो यह ~/.claude/settings.json में इस तरह की प्रविष्टियाँ लिखता है:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}

Claude Code फिर हर टूल कॉल से पहले failproofai --hook PreToolUse को एक सबप्रोसेस के रूप में चलाता है, stdin पर एक JSON पेलोड भेजता है।

​

पेलोड प्रारूप

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
  "cwd": "/home/user/myproject",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "sudo apt install nodejs" }
}

PostToolUse इवेंट के लिए, पेलोड में tool_result भी होता है जिसमें टूल का आउटपुट होता है।

हैंडलर 1 MB stdin लिमिट लागू करता है। इस सीमा से अधिक पेलोड छोड़ दिए जाते हैं और सभी पॉलिसीज़ निहित रूप से अनुमति देती हैं।

​

रेस्पांस प्रारूप

Deny (PreToolUse):

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
  }
}

Deny (PostToolUse):

{
  "hookSpecificOutput": {
    "additionalContext": "Blocked by failproofai because: API key detected in output"
  }
}

Instruct (किसी भी ईवेंट को छोड़कर Stop):

{
  "hookSpecificOutput": {
    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
  }
}

Stop event instruct:

• एक्जिट कोड: 2
• कारण stderr में लिखा गया (stdout में नहीं)

Allow:

• एक्जिट कोड: 0
• खाली stdout

संदेश के साथ Allow:

allow(message) एक पॉलिसी को Claude को सूचनात्मक संदर्भ वापस भेजने देता है यहाँ तक कि जब ऑपरेशन की अनुमति हो। हुक हैंडलर निम्नलिखित JSON को stdout में लिखता है (एक कॉन्फ़िग फ़ाइल में नहीं — यह हैंडलर का Claude Code को रेस्पांस है, जैसे deny और instruct रेस्पांस के ऊपर):

// हुक हैंडलर प्रक्रिया द्वारा stdout में लिखा गया
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}

• एक्जिट कोड: 0 (ऑपरेशन की अनुमति है)
• जब कई पॉलिसीज़ संदेश के साथ allow देते हैं, तो उनके संदेश नई पंक्तियों के साथ जुड़ जाते हैं एक एकल additionalContext स्ट्रिंग में
• अगर कोई पॉलिसी संदेश प्रदान नहीं करती है, तो stdout खाली है (पहले जैसे)

​

प्रोसेसिंग पाइपलाइन

src/hooks/handler.ts पूरी पाइपलाइन को लागू करता है:

stdin JSON
  → पेलोड को पार्स करें (अधिकतम 1 MB)
  → सेशन मेटाडेटा निकालें (session_id, cwd, tool_name, tool_input, आदि)
  → readMergedHooksConfig(cwd)    ← प्रोजेक्ट + लोकल + ग्लोबल कॉन्फ़िग को मर्ज करता है
  → सक्षम बिल्ट-इन पॉलिसीज़ को हल किए गए पैरामीटर के साथ रजिस्टर करें
  → customPoliciesPath से कस्टम पॉलिसीज़ लोड करें (यदि सेट हो)
  → कस्टम पॉलिसीज़ को पॉलिसी रजिस्ट्री में रजिस्टर करें
  → सभी पॉलिसीज़ का मूल्यांकन करें (पहले बिल्ट-इन्स, फिर कस्टम)
      → पहला deny शॉर्ट-सर्किट करता है
      → instruct निर्णय जमा होते हैं
      → allow संदेश जमा होते हैं
  → stdout में JSON निर्णय लिखें
  → इवेंट को ~/.failproofai/hook-activity.jsonl में रखें
  → एक्जिट करें

बिना LLM कॉल के विशिष्ट पेलोड के लिए पूरी प्रक्रिया 100ms में पूरी हो जाती है।

---

​

कॉन्फ़िग लोडिंग

src/hooks/hooks-config.ts तीन-स्कोप कॉन्फ़िग लोडिंग को लागू करता है।

[1] {cwd}/.failproofai/policies-config.json        ← प्रोजेक्ट  (सर्वोच्च प्राथमिकता)
[2] {cwd}/.failproofai/policies-config.local.json  ← लोकल
[3] ~/.failproofai/policies-config.json             ← ग्लोबल   (सबसे कम प्राथमिकता)

मर्ज लॉजिक:

• enabledPolicies - सभी तीन फ़ाइलों में डीडुप्लिकेटेड यूनियन
• policyParams - प्रति-पॉलिसी कुंजी, पहली फ़ाइल जो इसे परिभाषित करती है पूरी तरह जीतती है
• customPoliciesPath - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है
• llm - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है

वेब डैशबोर्ड पढ़ने और लिखने के लिए readHooksConfig() (केवल ग्लोबल) का उपयोग करता है, क्योंकि इसे प्रोजेक्ट cwd के साथ नहीं चलाया जाता है।

---

​

पॉलिसी मूल्यांकन

src/hooks/policy-evaluator.ts क्रम में पॉलिसीज़ चलाता है।

प्रत्येक पॉलिसी के लिए:

1. पॉलिसी के params स्कीमा को देखें (यदि इसके पास है)।
2. मर्ज किए गए कॉन्फ़िग से policyParams[policy.name] को पढ़ें।
3. उपयोगकर्ता-प्रदान किए गए मानों को स्कीमा डिफ़ॉल्ट पर मर्ज करें ctx.params का उत्पादन करने के लिए।
4. हल किए गए संदर्भ के साथ policy.fn(ctx) कॉल करें।
5. यदि परिणाम deny है, तो तुरंत रुकें और वह निर्णय दें।
6. यदि परिणाम instruct है, तो संदेश जमा करें और जारी रखें।
7. यदि परिणाम allow है, तो अगली पॉलिसी पर जाएं।

सभी पॉलिसीज़ चलने के बाद:

• अगर कोई deny दिया गया था, तो deny रेस्पांस उत्सर्जित करें।
• यदि कोई instruct रिटर्न एकत्र किए गए हैं, तो सभी संदेशों को जुड़े हुए एकल instruct रेस्पांस उत्सर्जित करें।
• अन्यथा, allow रेस्पांस उत्सर्जित करें (खाली stdout, एक्जिट 0)।

---

​

बिल्ट-इन पॉलिसीज़

src/hooks/builtin-policies.ts सभी 39 बिल्ट-इन पॉलिसीज़ को BuiltinPolicyDefinition ऑब्जेक्ट के रूप में परिभाषित करता है:

interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}

जो पॉलिसीज़ params स्वीकार करती हैं वे प्रत्येक पैरामीटर के लिए प्रकार और डिफ़ॉल्ट के साथ PolicyParamsSchema की घोषणा करती हैं। पॉलिसी मूल्यांकनकर्ता fn को कॉल करने से पहले हल किए गए मानों को ctx.params में इंजेक्ट करता है। पॉलिसी फ़ंक्शन ctx.params को पढ़ते हैं बिना null-गार्डिंग के क्योंकि डिफ़ॉल्ट हमेशा पहले लागू होते हैं।

पॉलिसीज़ के अंदर पैटर्न मिलान पार्स किए गए कमांड टोकन (argv) का उपयोग करता है, कच्ची स्ट्रिंग मिलान नहीं। यह शेल ऑपरेटर इंजेक्शन के माध्यम से बाईपास को रोकता है (उदाहरण के लिए sudo systemctl status * के लिए एक पैटर्न ; rm -rf / को अपेंड करके बाईपास नहीं किया जा सकता)।

---

​

कस्टम पॉलिसीज़

src/hooks/custom-hooks-registry.ts एक globalThis-समर्थित रजिस्ट्री को लागू करता है:

const REGISTRY_KEY = "__failproofai_custom_hooks__";

export const customPolicies = {
  add(hook: CustomHook): void { ... }
};

export function getCustomHooks(): CustomHook[] { ... }
export function clearCustomHooks(): void { ... }  // परीक्षणों में उपयोग किया जाता है

src/hooks/custom-hooks-loader.ts उपयोगकर्ता की पॉलिसी फ़ाइल लोड करता है:

1. कॉन्फ़िग से customPoliciesPath पढ़ें; अनुपस्थित होने पर छोड़ें।
2. पूर्ण पथ में हल करें; फ़ाइल मौजूद है यह जाँचें।
3. सभी from "failproofai" आयात को वास्तविक dist पथ में फिर से लिखें ताकि customPolicies समान globalThis रजिस्ट्री को हल करे।
4. ESM संगतता सुनिश्चित करने के लिए संक्रमणीय स्थानीय आयात को पुनरावर्ती रूप से फिर से लिखें।
5. अस्थायी .mjs फ़ाइलें लिखें और entry फ़ाइल को import() करें।
6. getCustomHooks() को कॉल करके पंजीकृत हुक्स को पुनः प्राप्त करें।
7. finally ब्लॉक में सभी अस्थायी फ़ाइलें साफ करें।

किसी भी त्रुटि पर (फ़ाइल नहीं मिली, syntax त्रुटि, आयात विफलता), त्रुटि को ~/.failproofai/hook.log में लॉग किया जाता है और लोडर एक खाली सरणी देता है। बिल्ट-इन पॉलिसीज़ प्रभावित नहीं होती हैं।

कस्टम पॉलिसीज़ का मूल्यांकन सभी बिल्ट-इन पॉलिसीज़ के बाद किया जाता है। एक कस्टम पॉलिसी deny अभी भी आगे की कस्टम पॉलिसीज़ को शॉर्ट-सर्किट करता है (लेकिन सभी बिल्ट-इन्स पहले ही चल चुकी होती हैं)।

---

​

गतिविधि लॉगिंग

प्रत्येक हुक ईवेंट के बाद, हैंडलर ~/.failproofai/hook-activity.jsonl में एक JSONL पंक्ति को अपेंड करता है:

{
  "timestamp": "2026-04-06T12:34:56.789Z",
  "sessionId": "abc123",
  "eventType": "PreToolUse",
  "toolName": "Bash",
  "policyName": "block-sudo",
  "decision": "deny",
  "reason": "sudo command blocked by failproofai",
  "durationMs": 12
}

एक पंक्ति प्रति पॉलिसी जिसने एक गैर-allow निर्णय दिया। Allow निर्णय लॉग नहीं होते हैं (फ़ाइल को छोटा रखने के लिए)।

---

​

डैशबोर्ड आर्किटेक्चर

डैशबोर्ड एक Next.js 16 एप्लिकेशन है जो App Router के साथ React Server Components और Server Actions का उपयोग करता है।

app/
  layout.tsx                  ← रूट लेआउट (थीम, टेलीमेट्री, नेव)
  projects/page.tsx           ← सर्वर कंपोनेंट: सभी Claude प्रोजेक्ट सूचीबद्ध करें
  project/[name]/page.tsx     ← सर्वर कंपोनेंट: प्रोजेक्ट में सेशन सूचीबद्ध करें
  project/[name]/session/
    [sessionId]/page.tsx      ← सर्वर कंपोनेंट: सेशन दर्शक रेंडर करें
  policies/page.tsx           ← क्लाइंट कंपोनेंट: पॉलिसी प्रबंधन + गतिविधि लॉग
  actions/
    get-hooks-config.ts       ← कॉन्फ़िग + पॉलिसी सूची पढ़ें
    update-hooks-config.ts    ← पॉलिसी को चालू/बंद करें
    update-policy-params.ts   ← पॉलिसी पैरामीटर अपडेट करें
    get-hook-activity.ts      ← गतिविधि लॉग को पेजिनेट/खोजें
    install-hooks-web.ts      ← ब्राउज़र से हुक्स को इंस्टॉल/हटाएँ
  api/
    download/[project]/[session]/route.ts   ← प्रति-CLI सेशन एक्सपोर्ट (JSONL या JSON)

डेटा प्रवाह:

• पेज कंपोनेंट प्रोजेक्ट/सेशन डेटा को सीधे फ़ाइलसिस्टम से पढ़ने के लिए lib/projects.ts और lib/log-entries.ts को कॉल करते हैं (पढ़ने के लिए कोई API परत नहीं)।
• पॉलिसीज़ पेज सभी mutations के लिए Server Actions का उपयोग करता है (टॉगल, params अपडेट, इंस्टॉल/हटाएँ)।
• सेशन दर्शक Claude के JSONL ट्रांसक्रिप्ट प्रारूप को पार्स करता है और संदेशों और टूल कॉल की एक टाइमलाइन रेंडर करता है।

मुख्य डिज़ाइन निर्णय:

• कोई डेटाबेस नहीं - सभी स्थायी स्थिति सादे फ़ाइलों में है (~/.failproofai/, ~/.claude/projects/)।
• Mutations के लिए Server Actions - CRUD संचालन के लिए कोई REST API आवश्यक नहीं।
• पढ़ने के पृष्ठों के लिए React Server Components - तेज़ प्रारंभिक लोड, डेटा फ़ेचिंग के लिए कोई क्लाइंट बंडल नहीं।
• क्लाइंट कंपोनेंट केवल जहाँ आवश्यकता हो (पॉलिसी टॉगल, गतिविधि खोज, लॉग दर्शक)।

---

​

फ़ाइल लेआउट

failproofai/
├── bin/
│   └── failproofai.mjs           # CLI राउटर (hook / dashboard / install / आदि)
├── src/hooks/
│   ├── handler.ts                # हुक ईवेंट पाइपलाइन
│   ├── builtin-policies.ts       # 39 पॉलिसी परिभाषाएं
│   ├── policy-evaluator.ts       # पॉलिसी निष्पादन इंजन
│   ├── policy-registry.ts        # पॉलिसी पंजीकरण और लुकअप
│   ├── policy-types.ts           # TypeScript इंटरफेस
│   ├── hooks-config.ts           # मल्टी-स्कोप कॉन्फ़िग लोडिंग
│   ├── custom-hooks-registry.ts  # globalThis-समर्थित हुक रजिस्ट्री
│   ├── custom-hooks-loader.ts    # उपयोगकर्ता JS हुक्स के लिए ESM लोडर
│   ├── manager.ts                # install / remove / list संचालन
│   ├── install-prompt.ts         # इंटरैक्टिव पॉलिसी चयन प्रॉम्प्ट
│   ├── hook-logger.ts            # hook.log में लॉगिंग
│   ├── hook-activity-store.ts    # hook-activity.jsonl में गतिविधि को रखें
│   └── llm-client.ts             # LLM API क्लाइंट (AI-संचालित पॉलिसीज़ के लिए)
├── app/                          # Next.js डैशबोर्ड (पृष्ठ + Server actions)
├── lib/                          # साझा उपयोगिताएँ
│   ├── projects.ts               # फ़ाइलसिस्टम से Claude प्रोजेक्ट गणना करें
│   ├── log-entries.ts            # Claude ट्रांसक्रिप्ट JSONL प्रारूप को पार्स करें
│   ├── paths.ts                  # सिस्टम पथ हल करें
│   └── ...
├── components/                   # साझा React UI कंपोनेंट
├── contexts/                     # React context प्रदाता (थीम, ऑटो-रीफ्रेश, टेलीमेट्री)
├── examples/                     # उदाहरण कस्टम हुक फ़ाइलें
└── __tests__/                    # यूनिट और E2E परीक्षण