> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> कॉन्फ़िग फ़ाइल प्रारूप, तीन-स्कोप सिस्टम, और मर्ज नियम

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

***

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

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

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

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

### मर्ज नियम

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

```text theme={null}
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`** - पहला स्कोप जो किसी दिए गए नीति के लिए पैरामीटर परिभाषित करता है वह पूरी तरह जीत जाता है। नीति के पैरामीटर के मान में कोई गहरा मर्जिंग नहीं होता।

```text theme={null}
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
```

```text theme={null}
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`** - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है।

***

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

```json theme={null}
{
  "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` द्वारा दिखाए गए नीति पहचानकर्ता से मेल खाना चाहिए। संपूर्ण सूची के लिए [बिल्ट-इन पॉलिसीज़](/hi/built-in-policies) देखें।

`enabledPolicies` में नहीं होने वाली नीतियां निष्क्रिय होती हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों।

### `policyParams`

प्रकार: `Record<string, Record<string, unknown>>`

प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति [बिल्ट-इन पॉलिसीज़](/hi/built-in-policies) में अपने उपलब्ध पैरामीटर को दस्तावेज़ित करती है।

यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते, तो नीति के बिल्ट-इन डिफ़ॉल्ट का उपयोग किया जाता है। वे उपयोगकर्ता जो `policyParams` को बिल्कुल कॉन्फ़िगर नहीं करते, उन्हें पिछले संस्करणों के समान व्यवहार मिलता है।

नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियों को हुक-फायर समय पर चुप्पी से अनदेखा किया जाता है लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनियों के रूप में फ़्लैग किया जाता है।

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

प्रकार: `string` (वैकल्पिक)

एक संदेश जो जोड़ा जाता है कारण जब कोई नीति `deny` या `instruct` देता है। इसका उपयोग Claude को नीति को संशोधित किए बिना कार्रवाई योग्य निर्देशन देने के लिए करें।

किसी भी नीति प्रकार के साथ काम करता है — बिल्ट-इन, कस्टम (`custom/`), प्रोजेक्ट कन्वेंशन (`.failproofai-project/`), या उपयोगकर्ता कन्वेंशन (`.failproofai-user/`)।

```json theme={null}
{
  "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>` द्वारा सेट किया जाता है (पाथ को निरपेक्ष के लिए हल किया जाता है फिर संग्रहीत किया जाता है)।

फ़ाइल प्रत्येक हुक ईवेंट पर ताज़ी लोड की जाती है - कोई कैशिंग नहीं है। विस्तार के लिए [कस्टम पॉलिसीज़](/hi/custom-policies) देखें।

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

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

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

**फ़ाइल मिलान:** केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फ़ाइलें लोड की जाती हैं (उदा. `security-policies.mjs`, `workflow-policies.js`)। निर्देशिका में अन्य फ़ाइलें अनदेखी की जाती हैं।

**कोई कॉन्फ़िग की आवश्यकता नहीं:** कन्वेंशन नीतियों के लिए `policies-config.json` में प्रविष्टियों की आवश्यकता नहीं है। बस निर्देशिका में फ़ाइलें डालें और अगली हुक ईवेंट पर उन्हें चुना जाएगा।

**यूनियन लोडिंग:** प्रोजेक्ट और उपयोगकर्ता दोनों कन्वेंशन निर्देशिकाएं स्कैन की जाती हैं। दोनों स्तरों से सभी मेल खाने वाली फ़ाइलें लोड की जाती हैं (`customPoliciesPath` के विपरीत जो पहले-स्कोप-जीत का उपयोग करता है)।

अधिक विवरण और उदाहरणों के लिए [कस्टम पॉलिसीज़](/hi/custom-policies) देखें।

### `llm`

प्रकार: `object` (वैकल्पिक)

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

```json theme={null}
{
  "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](https://cursor.com/docs/hooks) के अनुसार एक फ्लैट ऐरे में; फ़ाइल एक टॉप-लेवल `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](https://opencode.ai/docs/plugins/) देखें।
  * **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 में साझा)

एक विशिष्ट एजेंट को target करने के लिए `--cli claude|codex|copilot|cursor|opencode|pi|hermes` पास करें (space-separated या repeated किसी भी subset के लिए):

```bash theme={null}
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` को कमिट करें:

```json theme={null}
{
  "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 को प्रभावित किए।