कॉन्फ़िगरेशन

failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करता है यह नियंत्रित करने के लिए कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कहां से कस्टम नीतियां लोड की जाती हैं। कॉन्फ़िगरेशन आपकी टीम के साथ साझा करने के लिए आसान बनाया गया है - इसे अपने रेपो में कमिट करें और हर डेवलपर को एक जैसा एजेंट सेफ्टी नेट मिले।

कॉन्फ़िगरेशन स्कोप

तीन कॉन्फ़िगरेशन स्कोप हैं, जिनका मूल्यांकन प्राथमिकता क्रम में किया जाता है:

स्कोप	फ़ाइल पाथ	उद्देश्य
project	`.failproofai/policies-config.json`	प्रति-रेपो सेटिंग्स, संस्करण नियंत्रण में कमिट की गई
local	`.failproofai/policies-config.local.json`	व्यक्तिगत प्रति-रेपो ओवरराइड, gitignored
global	`~/.failproofai/policies-config.json`	उपयोगकर्ता-स्तरीय डिफ़ॉल्ट सभी प्रोजेक्ट्स में

जब failproofai को एक हुक ईवेंट मिलता है, तो यह सभी तीन फ़ाइलों को लोड और मर्ज करता है जो वर्तमान कार्य निर्देशिका के लिए मौजूद हैं।

मर्ज नियम

enabledPolicies - सभी तीन स्कोप का संघ। कोई भी नीति जो किसी भी स्तर पर सक्षम है, सक्रिय होती है।

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplicated union

policyParams - पहला स्कोप जो किसी दिए गए नीति के लिए पैरामीटर परिभाषित करता है वह पूरी तरह जीत जाता है। नीति के पैरामीटर के मान में कोई गहरा मर्जिंग नहीं होता।

project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project wins, global ignored

project:  (no block-sudo entry)
local:    (no block-sudo entry)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← falls through to global

customPoliciesPath - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है। llm - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है।

कॉन्फ़िग फ़ाइल प्रारूप

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "sanitize-jwt",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "block-rm-rf": {
      "allowPaths": ["/tmp"]
    },
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  },
  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
}

फ़ील्ड संदर्भ

`enabledPolicies`

प्रकार: string[] सक्षम करने के लिए नीति के नाम की सूची। नाम बिल्कुल failproofai policies द्वारा दिखाए गए नीति पहचानकर्ता से मेल खाना चाहिए। संपूर्ण सूची के लिए बिल्ट-इन पॉलिसीज़ देखें। enabledPolicies में नहीं होने वाली नीतियां निष्क्रिय होती हैं, भले ही उनके पास policyParams में प्रविष्टियां हों।

`policyParams`

प्रकार: Record<string, Record<string, unknown>> प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति बिल्ट-इन पॉलिसीज़ में अपने उपलब्ध पैरामीटर को दस्तावेज़ित करती है। यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते, तो नीति के बिल्ट-इन डिफ़ॉल्ट का उपयोग किया जाता है। वे उपयोगकर्ता जो policyParams को बिल्कुल कॉन्फ़िगर नहीं करते, उन्हें पिछले संस्करणों के समान व्यवहार मिलता है। नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियों को हुक-फायर समय पर चुप्पी से अनदेखा किया जाता है लेकिन जब आप failproofai policies चलाते हैं तो चेतावनियों के रूप में फ़्लैग किया जाता है।

`hint` (क्रॉस-कटिंग)

प्रकार: string (वैकल्पिक) एक संदेश जो जोड़ा जाता है कारण जब कोई नीति deny या instruct देता है। इसका उपयोग Claude को नीति को संशोधित किए बिना कार्रवाई योग्य निर्देशन देने के लिए करें। किसी भी नीति प्रकार के साथ काम करता है — बिल्ट-इन, कस्टम (custom/), प्रोजेक्ट कन्वेंशन (.failproofai-project/), या उपयोगकर्ता कन्वेंशन (.failproofai-user/)।

{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}

जब block-force-push अस्वीकार करता है, तो Claude को यह दिखता है: “Force-pushing is blocked. Try creating a fresh branch instead.” गैर-स्ट्रिंग मान और खाली स्ट्रिंग्स को चुप्पी से अनदेखा किया जाता है। यदि hint सेट नहीं है, तो व्यवहार अपरिवर्तित रहता है (पश्चविमुखी-संगत)।

`customPoliciesPath`

प्रकार: string (निरपेक्ष पाथ) कस्टम हुक नीतियों वाली JavaScript फ़ाइल का पाथ। यह स्वचालित रूप से failproofai policies --install --custom <path> द्वारा सेट किया जाता है (पाथ को निरपेक्ष के लिए हल किया जाता है फिर संग्रहीत किया जाता है)। फ़ाइल प्रत्येक हुक ईवेंट पर ताज़ी लोड की जाती है - कोई कैशिंग नहीं है। विस्तार के लिए कस्टम पॉलिसीज़ देखें।

कन्वेंशन-आधारित नीतियां

स्पष्ट customPoliciesPath के अलावा, failproofai स्वचालित रूप से .failproofai/policies/ निर्देशिकाओं से नीति फ़ाइलों की खोज करता है और लोड करता है:

स्तर	निर्देशिका	स्कोप
परियोजना	`.failproofai/policies/`	संस्करण नियंत्रण के माध्यम से टीम के साथ साझा किया गया
उपयोगकर्ता	`~/.failproofai/policies/`	व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू

फ़ाइल मिलान: केवल *policies.{js,mjs,ts} से मेल खाने वाली फ़ाइलें लोड की जाती हैं (उदा. security-policies.mjs, workflow-policies.js)। निर्देशिका में अन्य फ़ाइलें अनदेखी की जाती हैं। कोई कॉन्फ़िग की आवश्यकता नहीं: कन्वेंशन नीतियों के लिए policies-config.json में प्रविष्टियों की आवश्यकता नहीं है। बस निर्देशिका में फ़ाइलें डालें और अगली हुक ईवेंट पर उन्हें चुना जाएगा। यूनियन लोडिंग: प्रोजेक्ट और उपयोगकर्ता दोनों कन्वेंशन निर्देशिकाएं स्कैन की जाती हैं। दोनों स्तरों से सभी मेल खाने वाली फ़ाइलें लोड की जाती हैं (customPoliciesPath के विपरीत जो पहले-स्कोप-जीत का उपयोग करता है)। अधिक विवरण और उदाहरणों के लिए कस्टम पॉलिसीज़ देखें।

`llm`

प्रकार: object (वैकल्पिक) उन नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन जो AI कॉल करते हैं। अधिकांश सेटअप के लिए आवश्यक नहीं है।

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

CLI से कॉन्फ़िगरेशन प्रबंधित करना

policies --install और policies --uninstall कमांड आपके एजेंट CLI की हुक सेटिंग्स फ़ाइल (हुक एंट्री पॉइंट) में लिखते हैं, जबकि policies-config.json वह फ़ाइल है जिसे आप सीधे प्रबंधित करते हैं। दोनों अलग हैं:

एजेंट CLI सेटिंग्स — एजेंट को बताता है कि प्रत्येक टूल उपयोग पर failproofai --hook <event> को कॉल करना है:
- Claude Code: ~/.claude/settings.json (उपयोगकर्ता), <cwd>/.claude/settings.json (प्रोजेक्ट), <cwd>/.claude/settings.local.json (लोकल)
- OpenAI Codex: ~/.codex/hooks.json (उपयोगकर्ता), <cwd>/.codex/hooks.json (प्रोजेक्ट) — Codex के पास local स्कोप नहीं है
- GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json (उपयोगकर्ता), <cwd>/.github/hooks/failproofai.json (प्रोजेक्ट) — Copilot के पास कोई local स्कोप नहीं है। हुक एंट्रीज़ Copilot के OS-keyed bash/powershell कमांड फ़ील्ड का उपयोग करते हैं timeoutSec के साथ; फ़ाइल एक टॉप-लेवल version: 1 मार्कर ले जाती है। Copilot CLI समर्थन beta है जबकि हम events.jsonl रिकॉर्ड स्कीमा को सत्यापित करते हैं (जिसे सार्वजनिक दस्तावेज़ निर्दिष्ट नहीं करते) अधिक वास्तविक-दुनिया सत्रों के विरुद्ध।
- Cursor Agent (beta): ~/.cursor/hooks.json (उपयोगकर्ता), <cwd>/.cursor/hooks.json (प्रोजेक्ट) — Cursor के पास कोई local स्कोप नहीं है। हुक एंट्रीज़ Claude-shaped {type, command, timeout} फॉर्म का उपयोग करते हैं (कोई bash/powershell विभाजन नहीं), लेकिन camelCase ईवेंट कुंजियों के तहत संग्रहीत (preToolUse, beforeSubmitPrompt, …) Cursor के hooks schema के अनुसार एक फ्लैट ऐरे में; फ़ाइल एक टॉप-लेवल version: 1 मार्कर ले जाती है। हैंडलर camelCase → PascalCase को CURSOR_EVENT_MAP के माध्यम से कैनोनिकलाइज़ करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रूप से चलें। Cursor Agent समर्थन beta है जबकि हम Cursor के ट्रांसक्रिप्ट को सत्यापित करते हैं (सार्वजनिक दस्तावेज़ में निर्दिष्ट नहीं) अधिक वास्तविक-दुनिया इंस्टॉल्स के विरुद्ध।
- OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (उपयोगकर्ता), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (प्रोजेक्ट) — OpenCode के पास कोई local स्कोप नहीं है। अन्य पाँच CLI के विपरीत, OpenCode के पास कोई बाहरी-कमांड हुक सिस्टम नहीं है: यह JS/TS प्लगइन को opencode.json में plugin: [] ऐरे के माध्यम से स्पष्ट रूप से पंजीकृत करके इन-प्रॉसेस लोड करता है (.opencode/plugins/ से ऑटो-डिस्कवरी नहीं है कि प्लगइन opencode v1.14.33 पर कैसे लोड होते हैं)। इंस्टॉल एक छोटा जेनरेटेड प्लगइन शिम छोड़ता है जो failproofai बाइनरी को subprocess-कॉल करता है और बाइनरी के Claude-shape JSON प्रतिक्रिया को प्लगइन शब्दावली में वापस अनुवाद करता है: throw new Error() टूल-ईवेंट deny के लिए (टूल कॉल को रद्द करता है), client.session.prompt(...) instruct AND के लिए Stop / SubagentStop deny (deny कारण को अगले उपयोगकर्ता संदेश के रूप में जमा करता है — एकमात्र force-retry चैनल क्योंकि session.idle केवल-अधिसूचना है और इससे throw करना एक no-op है), और allow के लिए no-op। शिम both टूल नाम (lowercase → PascalCase OPENCODE_TOOL_MAP के माध्यम से) और tool-input arg कुंजियां (camelCase → snake_case OPENCODE_TOOL_INPUT_MAP के माध्यम से Read / Write / Edit के लिए, उदा. filePath → file_path, oldString → old_string) कैनोनिकलाइज़ करता है बाइनरी में अग्रेषित करने से पहले, इसलिए path-checking builtins जैसे block-read-outside-cwd, block-env-files, और block-secrets-write OpenCode tool कॉल पर अपरिवर्तित रूप से चलते हैं। सत्र opencode के SQLite DB में ~/.local/share/opencode/opencode.db में रहते हैं; डैशबोर्ड का सत्र दर्शक opencode db --format json और opencode export <id> के माध्यम से उन्हें पढ़ता है। OpenCode समर्थन beta है जबकि हम संस्करणों में व्यवहार को सत्यापित करते हैं और अधिक वास्तविक-दुनिया सत्रों के विरुद्ध। OpenCode plugins docs देखें।
- Pi (beta): ~/.pi/agent/settings.json (उपयोगकर्ता), <cwd>/.pi/settings.json (प्रोजेक्ट) — Pi के पास कोई local स्कोप नहीं है। Pi स्टार्टअप पर TypeScript extension पैकेज लोड करता है; सेटिंग्स फ़ाइल एक फ्लैट स्ट्रिंग ऐरे {"packages": ["./relative/path", …]} है। failproofai एक single packages-array एंट्री लिखता है जो अपनी bundled pi-extension/ निर्देशिका की ओर इशारा करता है। एक्सटेंशन आंतरिक रूप से Pi के tool_call / user_bash / input / session_start ईवेंट्स की सदस्यता लेता है और failproofai --hook <Event> --cli pi के लिए shell बाहर निकालता है; हैंडलर underscore_lower_snake_case → PascalCase को PI_EVENT_MAP के माध्यम से कैनोनिकलाइज़ करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रूप से चलें। Tool input args को PI_TOOL_INPUT_MAP के माध्यम से भी कैनोनिकलाइज़ किया जाता है (Pi के Read / Write / Edit path के बजाय file_path प्रदान करते हैं; शीर्ष-स्तरीय कुंजी को मैप करना block-env-files और block-secrets-write को चलने देता है — block-read-outside-cwd पहले से ही एक path fallback था)। Pi समर्थन beta है जबकि Pi का एक्सटेंशन API और session-log लेआउट स्थिर होता है।
- Hermes (hermes-agent): ~/.hermes/config.yaml (उपयोगकर्ता स्कोप केवल — Hermes के पास कोई project/local कॉन्फ़िग नहीं है)। Hermes एक Slack/Telegram गेटवे है, इसलिए एक इंस्टॉल हर प्लेटफॉर्म (Slack/Telegram/cli/cron) और आंतरिक subagents से tool कॉल को इंटरसेप्ट करता है। हुक एंट्रीज़ एक {command, timeout} pair (सेकंड में timeout) हैं एक hooks: map के तहत Hermes के snake_case ईवेंट्स द्वारा keyed (pre_tool_call / post_tool_call / on_session_start / on_session_end / subagent_stop); हैंडलर ईवेंट्स को HERMES_EVENT_MAP के माध्यम से और टूल नाम को HERMES_TOOL_MAP के माध्यम से कैनोनिकलाइज़ करता है ताकि बिल्ट-इन नीतियां अपरिवर्तित रूप से चलें। कॉन्फ़िग एक comment-preserving YAML Document round-trip के माध्यम से संपादित किया जाता है ताकि ऑपरेटर की अन्य सेटिंग्स जीवित रहें, और install hooks_auto_accept: true सेट करता है ताकि headless gateway (कोई TTY नहीं) consent प्रॉम्प्ट के बिना हुक चलाए। मूल्यांकनकर्ता Hermes के {"decision":"block","reason"} stdout contract उत्सर्जित करता है (Hermes exit कोड को अनदेखा करता है)। सीमाएं: Hermes के पास कोई turn-end Stop ईवेंट नहीं है, इसलिए require-*-before-stop builtins कभी इसके लिए नहीं चलते (inapplicable, broken नहीं); instruct allow-with-logged-note में degrade होता है (कोई additional-context चैनल नहीं); और output-secret redaction (sanitize-*) shell-hook contract के ऊपर tool output को rewrite नहीं कर सकता। Hermes भी एक offline audit स्रोत है — डैशबोर्ड अपने gateway सत्रों को सीधे ~/.hermes/state.db से पढ़ता है।
policies-config.json — failproofai को बताता है कि कौन सी नीतियों का मूल्यांकन करना है और किस पैरामीटर के साथ (सभी एजेंट CLIs में साझा)

failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli hermes --scope user
failproofai policies --install --cli claude codex copilot cursor opencode pi

जब --cli omit किया जाता है, failproofai पता लगाता है कि कौन से एजेंट CLIs installed हैं (which claude / which codex / which copilot / which cursor-agent / which opencode / which pi / which hermes):

एक CLI detected — prompt के बिना उस CLI को auto-select करता है।
Multiple CLIs detected एक interactive terminal में — एक arrow-key single-select प्रॉम्प्ट दिखाता है एक Detected (N) section (एक Install for all N detected aggregate row + प्रत्येक detected CLI individually के साथ) और एक Not installed (M) · install hooks ahead of time section में grouped (हर undetected supported CLI को एक forward-install विकल्प के रूप में सूचीबद्ध करता है (↑↓ move करने के लिए, Enter select करने के लिए, ^C quit करने के लिए))। uninstall flow केवल Detected section दिखाता है।
Multiple CLIs detected एक non-interactive run में (CI, कोई TTY नहीं) — prompt के बिना सभी detected CLIs के लिए install करता है।
None detected — claude को fallback करता है, एक warning के साथ कि कोई एजेंट बाइनरी PATH में नहीं मिला; हुक कमांड अभी भी लिखा जाता है ताकि यह तुरंत सक्रिय हो जाए जब आप एक install करते हैं।

आप किसी भी समय policies-config.json को सीधे edit कर सकते हैं; changes अगली हुक ईवेंट पर तुरंत प्रभावी होते हैं restart की आवश्यकता नहीं है।

उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-लेवल कॉन्फ़िग

अपने रेपो में .failproofai/policies-config.json को कमिट करें:

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}

प्रत्येक डेवलपर फिर व्यक्तिगत overrides के लिए .failproofai/policies-config.local.json (gitignored) बना सकता है बिना teammates को प्रभावित किए।

शुरू करें

मूल अवधारणाएँ

CLI

उपकरण

उन्नत

उदाहरण

कॉन्फ़िगरेशन