구성

​

설정 범위

​

병합 규칙

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

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← 중복 제거된 합집합

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

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project 우선, global 무시

project:  (block-sudo 항목 없음)
local:    (block-sudo 항목 없음)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← global까지 전달됨

​

설정 파일 형식

{
  "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

​

policyParams

​

hint (공통 옵션)

{
  "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."
    }
  }
}

​

customPoliciesPath

​

규칙 기반 정책

​

llm

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

​

CLI에서 설정 관리

• 에이전트 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 (베타): ~/.copilot/hooks/failproofai.json (사용자), <cwd>/.github/hooks/failproofai.json (프로젝트) — Copilot에는 local 범위가 없습니다. 훅 항목은 Copilot의 OS별 bash/powershell 명령 필드와 timeoutSec을 사용하며, 파일에는 최상위 version: 1 마커가 있습니다. Copilot CLI 지원은 events.jsonl 레코드 스키마(공개 문서에 명시되지 않음)를 더 많은 실제 세션에서 검증하는 동안 베타 상태입니다.
  • Cursor Agent (베타): ~/.cursor/hooks.json (사용자), <cwd>/.cursor/hooks.json (프로젝트) — Cursor에는 local 범위가 없습니다. 훅 항목은 Claude 형식의 {type, command, timeout} 형태를 사용하지만, Cursor의 hooks 스키마에 따라 camelCase 이벤트 키(preToolUse, beforeSubmitPrompt, …) 아래의 플랫 배열에 저장됩니다. 파일에는 최상위 version: 1 마커가 있습니다. 핸들러는 CURSOR_EVENT_MAP을 통해 camelCase를 PascalCase로 정규화하므로 기존 기본 정책이 변경 없이 실행됩니다. Cursor Agent 지원은 Cursor의 전사본 온디스크 형식(공개 문서에 명시되지 않음)을 더 많은 실제 설치 환경에서 검증하는 동안 베타 상태입니다.
  • OpenCode (베타): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (사용자), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (프로젝트) — OpenCode에는 local 범위가 없습니다. 다른 여섯 CLI와 달리 OpenCode에는 외부 명령 훅 시스템이 없습니다: opencode.json의 plugin: [] 배열을 통해 명시적으로 등록된 인프로세스 JS/TS 플러그인을 로드합니다 (.opencode/plugins/에서의 자동 검색은 opencode v1.14.33에서 플러그인이 로드되는 방식이 아닙니다). 설치 시 failproofai 바이너리를 서브프로세스로 호출하고 바이너리의 Claude 형식 JSON 응답을 플러그인 시맨틱으로 변환하는 소형 생성 플러그인 심(shim)을 생성합니다: 도구 이벤트 deny에는 throw new Error() (도구 호출 취소), instruct 및 Stop/SubagentStop deny에는 client.session.prompt(...) (deny 이유를 다음 사용자 메시지로 제출 — session.idle은 알림 전용이고 throw는 무작동이므로 이 채널이 유일한 강제 재시도 채널), allow에는 무작동. 심은 도구 이름(소문자 → OPENCODE_TOOL_MAP을 통한 PascalCase)과 도구 입력 인수 키(Read/Write/Edit에 대해 OPENCODE_TOOL_INPUT_MAP을 통한 camelCase → snake_case, 예: filePath → file_path, oldString → old_string)를 정규화한 후 바이너리로 전달하므로, block-read-outside-cwd, block-env-files, block-secrets-write와 같은 경로 확인 기본 정책이 OpenCode 도구 호출에서 변경 없이 실행됩니다. 세션은 ~/.local/share/opencode/opencode.db의 opencode SQLite DB에 저장되며, 대시보드의 세션 뷰어는 opencode db --format json 및 opencode export <id>를 통해 읽습니다. OpenCode 지원은 버전 간 동작과 더 많은 실제 세션을 검증하는 동안 베타 상태입니다. OpenCode 플러그인 문서를 참고하세요.
  • Pi (베타): ~/.pi/agent/settings.json (사용자), <cwd>/.pi/settings.json (프로젝트) — Pi에는 local 범위가 없습니다. Pi는 시작 시 TypeScript 확장 패키지를 로드하며, 설정 파일은 플랫 문자열 배열 {"packages": ["./relative/path", …]}입니다. failproofai는 번들된 pi-extension/ 디렉토리를 가리키는 단일 packages 배열 항목을 씁니다. 확장은 내부적으로 Pi의 tool_call/user_bash/input/session_start 이벤트를 구독하고 failproofai --hook <Event> --cli pi를 쉘 아웃합니다. 핸들러는 PI_EVENT_MAP을 통해 underscore_lower_snake_case를 PascalCase로 정규화하므로 기존 기본 정책이 변경 없이 실행됩니다. 도구 입력 인수도 PI_TOOL_INPUT_MAP을 통해 정규화됩니다 (Pi의 Read/Write/Edit는 file_path 대신 path를 전달하며, 최상위 키를 매핑하면 block-env-files와 block-secrets-write가 실행됩니다 — block-read-outside-cwd는 이미 path 폴백을 가지고 있었습니다). Pi 지원은 Pi의 확장 API와 세션 로그 레이아웃이 안정화되는 동안 베타 상태입니다.
  • Gemini CLI (베타): ~/.gemini/settings.json (사용자), <cwd>/.gemini/settings.json (프로젝트) — Gemini에는 local 범위가 없습니다 (failproofai가 노출하지 않는 /etc/gemini-cli/settings.json의 system 범위를 문서화하고 있습니다). 훅 항목은 기본적으로 matcher: "*"를 사용하는 Gemini의 {matcher, hooks: [...]} 매처 스키마로 래핑된 Claude의 {type, command, timeout} 형태를 사용합니다. 이벤트는 PascalCase(SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd)이며, 핸들러는 GEMINI_EVENT_MAP을 통해 Claude 표준 이름으로 매핑합니다. 도구 이름은 snake_case(run_shell_command, read_file, write_file, replace, …)이며, 핸들러는 GEMINI_TOOL_MAP을 통해 정규화하므로 기존 기본 정책이 변경 없이 실행됩니다. 정책 평가기는 Gemini의 플랫 {decision: "deny", reason} 형태 (Gemini의 “Golden Rule” exit-0 계약에 따른 선호 형식), BeforeAgent/AfterTool/SessionStart에서의 컨텍스트 주입을 위한 {hookSpecificOutput: {hookEventName, additionalContext}}, 그리고 강제 재시도 시맨틱을 위한 AfterAgent의 {decision: "block", reason}을 반환합니다. Gemini CLI 지원은 실제 환경 커버리지를 넓히는 동안 베타 상태입니다. Gemini CLI 훅 문서를 참고하세요.
• policies-config.json — failproofai에게 어떤 정책을 평가할지, 어떤 파라미터로 평가할지 알려줍니다 (모든 에이전트 CLI에서 공유)

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 gemini --scope project
failproofai policies --install --cli claude codex copilot cursor opencode pi gemini

• 하나의 CLI 감지됨 — 확인 없이 해당 CLI를 자동 선택합니다.
• 여러 CLI가 대화형 터미널에서 감지됨 — Detected (N) 섹션(개별 감지된 CLI와 Install for all N detected 집계 행 포함) 및 Not installed (M) · install hooks ahead of time 섹션(감지되지 않은 지원 CLI를 사전 설치 옵션으로 표시)이 있는 화살표 키 단일 선택 프롬프트를 표시합니다 (↑↓로 이동, Enter로 선택, ^C로 종료). 제거 흐름에는 Detected 섹션만 표시됩니다.
• 여러 CLI가 비대화형 실행에서 감지됨 (CI, TTY 없음) — 확인 없이 감지된 모든 CLI에 설치합니다.
• 감지된 CLI 없음 — PATH에서 에이전트 바이너리를 찾을 수 없다는 경고와 함께 claude로 폴백합니다. 훅 명령은 여전히 작성되므로 에이전트를 설치하는 즉시 활성화됩니다.

​

예시: 팀 기본값이 포함된 프로젝트 수준 설정

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