기본 제공 정책 - FailproofAI

failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39가지 기본 제공 정책이 포함되어 있습니다. 각 정책은 특정 훅 이벤트 유형과 도구 이름에 따라 실행됩니다. 19개의 정책은 코드 작성 없이 동작을 조정할 수 있는 파라미터를 허용합니다. 5개의 워크플로 정책은 Claude가 중단하기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다.

개요

정책은 다음과 같은 카테고리로 분류됩니다:

카테고리	정책	훅 유형
위험한 명령어	block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands	PreToolUse
인프라 명령어	block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline	PreToolUse
시크릿(새니타이저)	sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens	PostToolUse
환경	block-env-files, protect-env-vars	PreToolUse
파일 접근	block-read-outside-cwd, block-secrets-write	PreToolUse
Git	block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged	PreToolUse
데이터베이스	warn-destructive-sql, warn-schema-alteration	PreToolUse
경고	warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install	PreToolUse
패키지 매니저	prefer-package-manager	PreToolUse
워크플로	require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop	Stop

block- — 에이전트가 진행하지 못하도록 차단합니다.
warn- — 에이전트가 스스로 수정할 수 있도록 추가 컨텍스트를 제공합니다.
sanitize- — 에이전트가 확인하기 전에 도구 출력에서 민감한 데이터를 제거합니다.

네임스페이스

모든 정책은 <namespace>/<name> 슬롯에 위치합니다. 기본 제공 정책은 failproofai/ 네임스페이스에 속하며, 예를 들어 failproofai/sanitize-jwt와 같습니다. 네임스페이스는 유사한 짧은 이름을 가진 커스텀 또는 서드파티 정책을 함께 로드할 때 충돌을 방지합니다. 설정에서 기본 제공 정책을 짧은 이름 또는 전체 한정 이름으로 참조할 수 있으며, 두 형식 모두 동일한 정책으로 해석됩니다:

{
  "enabledPolicies": [
    "sanitize-jwt",
    "failproofai/block-rm-rf"
  ]
}

이름에 /가 없으면 failproofai는 기본 네임스페이스인 failproofai에 속하는 것으로 처리합니다. 이미 /가 포함된 이름(예: myorg/foo, custom/my-hook)은 그대로 유지됩니다.

require- — 조건이 충족될 때까지 Stop 이벤트를 차단합니다.

모든 정책은 policyParams에서 선택적 hint 필드를 지원합니다. hint는 Claude가 확인하는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 기본 제공, 커스텀, 관례 정책 모두에서 사용할 수 있습니다. 자세한 내용은 설정 → hint를 참조하세요.

위험한 명령어

에이전트가 되돌리기 어렵거나 호스트 시스템을 손상시킬 수 있는 작업을 실행하지 못하도록 방지합니다.

`block-sudo`

이벤트: PreToolUse (Bash)
기본값: sudo 명령어가 포함된 모든 명령을 차단합니다. sudo 키워드가 포함된 호출을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령 토큰에 대해 수행되어 셸 연산자 주입을 통한 우회를 방지합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용된 정확한 명령 접두사. 각 항목은 파싱된 argv 토큰과 매칭됩니다.

예시:

{
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    }
  }
}

이 설정으로 sudo systemctl status nginx는 허용되지만 sudo rm /etc/hosts는 차단됩니다.

패턴은 원시 명령 문자열이 아닌 파싱된 토큰과 매칭됩니다. 이를 통해 추가된 셸 연산자를 통한 우회를 방지합니다(예: sudo systemctl status x; rm -rf /는 sudo systemctl status *와 매칭되지 않습니다).

`block-rm-rf`

이벤트: PreToolUse (Bash)
기본값: rm -rf, rm -fr 및 유사한 재귀 삭제 형식을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPaths`	`string[]`	`[]`	재귀 삭제가 허용된 경로(예: `/tmp`).

예시:

{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp", "/var/cache"]
    }
  }
}

`block-curl-pipe-sh`

이벤트: PreToolUse (Bash)
기본값: curl <url> | bash, curl <url> | sh, wget <url> | bash 및 유사한 패턴을 차단합니다. 파라미터 없음.

`block-failproofai-commands`

이벤트: PreToolUse (Bash)
기본값: failproofai 자체를 제거하거나 비활성화하는 명령(예: npm uninstall failproofai, failproofai policies --uninstall)을 차단합니다. 파라미터 없음.

인프라 명령어

코딩 에이전트가 인프라 CLI를 실행하거나 CI/CD 파이프라인을 트리거하지 못하도록 차단합니다. 이 카테고리의 모든 정책은 옵트인(defaultEnabled: false)입니다. kubectl, terraform 등을 합법적으로 호출해야 하는 에이전트는 정책을 활성화하지 않는 한 영향을 받지 않습니다. 활성화된 경우, 명령이 allowPatterns의 항목과 일치하지 않는 한 해당 CLI의 모든 호출이 차단됩니다. 패턴 문법은 block-sudo와 동일합니다. 토큰은 파싱된 argv와 매칭되고, *는 하나의 토큰에 대한 와일드카드이며, 독립적인 셸 연산자(&&, ||, |, ;) 또는 셸 메타문자가 내장된 토큰을 포함하는 명령은 주입 우회를 방지하기 위해 허용 목록 매칭 전에 거부됩니다.

`block-kubectl`

이벤트: PreToolUse (Bash)
기본값: 모든 kubectl 호출을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용된 kubectl 명령 접두사.

예시:

{
  "policyParams": {
    "block-kubectl": {
      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
    }
  }
}

이 설정으로 kubectl get pods는 허용되지만 kubectl apply -f deploy.yaml은 차단됩니다.

`block-terraform`

이벤트: PreToolUse (Bash)
기본값: 모든 terraform 또는 tofu(OpenTofu) 호출을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용된 terraform/tofu 명령 접두사.

예시:

{
  "policyParams": {
    "block-terraform": {
      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
    }
  }
}

`block-aws-cli`

이벤트: PreToolUse (Bash)
기본값: 모든 aws CLI 호출을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용된 aws CLI 명령 접두사.

예시:

{
  "policyParams": {
    "block-aws-cli": {
      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
    }
  }
}

`block-gcloud`

이벤트: PreToolUse (Bash)
기본값: 모든 gcloud(Google Cloud) CLI 호출을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용된 gcloud 명령 접두사.

예시:

{
  "policyParams": {
    "block-gcloud": {
      "allowPatterns": ["gcloud auth list", "gcloud config list"]
    }
  }
}

`block-az-cli`

이벤트: PreToolUse (Bash)
기본값: 모든 az(Azure) CLI 호출을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용된 az CLI 명령 접두사.

예시:

{
  "policyParams": {
    "block-az-cli": {
      "allowPatterns": ["az account show", "az group list"]
    }
  }
}

`block-helm`

이벤트: PreToolUse (Bash)
기본값: 모든 helm 호출을 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	허용된 helm 명령 접두사.

예시:

{
  "policyParams": {
    "block-helm": {
      "allowPatterns": ["helm list", "helm status *"]
    }
  }
}

`block-gh-pipeline`

이벤트: PreToolUse (Bash)
기본값: 상태를 변경하거나 파이프라인을 트리거하는 다음 gh CLI 서브커맨드를 차단합니다:

gh workflow run, gh workflow enable, gh workflow disable
gh run rerun, gh run cancel
gh pr merge
gh release create, gh release delete
gh cache delete
gh secret set, gh secret delete

gh pr view, gh pr list, gh run list, gh release view, gh api repos/.../...와 같은 읽기 전용 gh 서브커맨드는 이 정책에 해당하지 않습니다. 이러한 명령은 워크플로 확인(failproofai의 require-ci-green-before-stop 포함)에 일상적으로 필요합니다. 파라미터:

파라미터	타입	기본값	설명
`allowPatterns`	`string[]`	`[]`	그렇지 않으면 차단될 특정 스크립트 호출을 허용합니다.

예시:

{
  "policyParams": {
    "block-gh-pipeline": {
      "allowPatterns": ["gh run rerun *"]
    }
  }
}

시크릿(새니타이저)

에이전트가 컨텍스트나 출력에 자격 증명을 유출하지 못하도록 방지합니다. 새니타이저 정책은 PostToolUse 이벤트에서 실행됩니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출할 때 이러한 정책은 Claude에게 반환되기 전에 출력을 검사합니다. 시크릿 패턴이 감지되면 출력이 다시 전달되는 것을 방지하는 deny 결정을 반환합니다.

`sanitize-jwt`

이벤트: PostToolUse (모든 도구)
기본값: JWT 토큰(.으로 구분된 세 개의 base64url 세그먼트)을 삭제합니다. 파라미터 없음.

`sanitize-api-keys`

이벤트: PostToolUse (모든 도구)
기본값: 일반적인 API 키 형식을 삭제합니다: Anthropic(sk-ant-), OpenAI(sk-), GitHub PAT(ghp_), AWS 액세스 키(AKIA), Stripe 키(sk_live_, sk_test_), Google API 키(AIza). 파라미터:

파라미터	타입	기본값	설명
`additionalPatterns`	`{ regex: string; label: string }[]`	`[]`	시크릿으로 처리할 추가 정규식 패턴.

예시:

{
  "policyParams": {
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
      ]
    }
  }
}

`sanitize-connection-strings`

이벤트: PostToolUse (모든 도구)
기본값: 자격 증명이 내장된 데이터베이스 연결 문자열을 삭제합니다(예: postgresql://user:password@host/db). 파라미터 없음.

`sanitize-private-key-content`

이벤트: PostToolUse (모든 도구)
기본값: PEM 블록(-----BEGIN PRIVATE KEY-----, -----BEGIN RSA PRIVATE KEY----- 등)을 삭제합니다. 파라미터 없음.

`sanitize-bearer-tokens`

이벤트: PostToolUse (모든 도구)
기본값: 토큰이 20자 이상인 Authorization: Bearer <token> 헤더를 삭제합니다. 파라미터 없음.

환경

에이전트가 민감한 환경 구성을 읽거나 노출하지 못하도록 보호합니다.

`block-env-files`

이벤트: PreToolUse (Bash, Read)
기본값: cat .env, .env를 파일 경로로 하는 Read 도구 호출 등을 통해 .env 파일을 읽는 것을 차단합니다. .envrc 또는 다른 환경 관련 파일은 차단하지 않으며, 정확히 .env로 명명된 파일만 차단합니다. 파라미터 없음.

`protect-env-vars`

이벤트: PreToolUse (Bash)
기본값: 환경 변수를 출력하는 명령(printenv, env, echo $VAR)을 차단합니다. 파라미터 없음.

파일 접근

에이전트가 프로젝트 경계 내에서 작업하고 민감한 파일에 접근하지 못하도록 유지합니다.

`block-read-outside-cwd`

이벤트: PreToolUse (Read, Bash)
기본값: 프로젝트 루트 외부의 파일 읽기를 차단합니다. 경계는 CLAUDE_PROJECT_DIR(Claude Code가 세션당 한 번 설정)이며, 해당 변수가 설정되지 않은 경우 세션의 현재 작업 디렉토리로 폴백합니다. 라이브 cwd 대신 프로젝트 루트를 사용하면 Claude가 하위 디렉토리로 cd한 후에도 경계가 안정적으로 유지됩니다. 파라미터:

파라미터	타입	기본값	설명
`allowPaths`	`string[]`	`[]`	프로젝트 루트 외부에 있더라도 허용되는 절대 경로 접두사.

예시:

{
  "policyParams": {
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company/config"]
    }
  }
}

`block-secrets-write`

이벤트: PreToolUse (Write, Edit)
기본값: 개인 키와 인증서에 일반적으로 사용되는 파일(id_rsa, id_ed25519, *.key, *.pem, *.p12, *.pfx)에 쓰기를 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`additionalPatterns`	`string[]`	`[]`	차단할 추가 파일 이름 패턴(글로브 스타일).

예시:

{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}

Git

실수로 인한 푸시, 강제 푸시, 되돌리기 어려운 브랜치 실수를 방지합니다.

`block-push-master`

이벤트: PreToolUse (Bash)
기본값: git push origin main 및 git push origin master를 차단합니다. 파라미터:

파라미터	타입	기본값	설명
`protectedBranches`	`string[]`	`["main", "master"]`	직접 푸시할 수 없는 브랜치 이름.

예시:

{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}

모든 브랜치로의 푸시를 허용하려면(사실상 enabledPolicies에서 제거하지 않고 이 정책을 비활성화), protectedBranches: []로 설정하세요.

`block-work-on-main`

이벤트: PreToolUse (Bash)
기본값: 작업 트리가 main 또는 master에 있는 동안 git commit, git merge, git rebase, git cherry-pick을 차단합니다. 브랜치 생성 및 전환(git checkout, git checkout -b, git switch, git switch -c)은 영향을 받지 않습니다. 파라미터:

파라미터	타입	기본값	설명
`protectedBranches`	`string[]`	`["main", "master"]`	commit/merge/rebase/cherry-pick이 차단되는 브랜치 이름.

`block-force-push`

이벤트: PreToolUse (Bash)
기본값: git push --force 및 git push -f를 차단합니다. 정책별 파라미터 없음. 대안을 제안하려면 공통 hint를 사용하세요:

{
  "policyParams": {
    "block-force-push": {
      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
    }
  }
}

`warn-git-amend`

이벤트: PreToolUse (Bash)
기본값: git commit --amend 실행 시 Claude에게 주의를 기울이도록 지시합니다. 명령을 차단하지 않습니다. 파라미터 없음.

`warn-git-stash-drop`

이벤트: PreToolUse (Bash)
기본값: git stash drop 실행 전 Claude에게 확인하도록 지시합니다. 명령을 차단하지 않습니다. 파라미터 없음.

`warn-all-files-staged`

이벤트: PreToolUse (Bash)
기본값: git add -A 또는 git add . 실행 시 Claude에게 스테이징 대상을 검토하도록 지시합니다. 명령을 차단하지 않습니다. 파라미터 없음.

데이터베이스

데이터베이스에 대해 실행되기 전에 파괴적인 SQL 작업을 감지합니다.

`warn-destructive-sql`

이벤트: PreToolUse (Bash)
기본값: DROP TABLE, DROP DATABASE, 또는 WHERE 절 없는 DELETE가 포함된 SQL 실행 전 Claude에게 확인하도록 지시합니다. 파라미터 없음.

`warn-schema-alteration`

이벤트: PreToolUse (Bash)
기본값: ALTER TABLE 구문 실행 전 Claude에게 확인하도록 지시합니다. 파라미터 없음.

경고

잠재적으로 위험하지만 파괴적이지 않은 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다.

`warn-large-file-write`

이벤트: PreToolUse (Write)
기본값: 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 지시합니다. 파라미터:

파라미터	타입	기본값	설명
`thresholdKb`	`number`	`1024`	경고가 발생하는 파일 크기 임계값(킬로바이트).

예시:

{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}

훅 핸들러는 페이로드에 대해 1 MB stdin 제한을 적용합니다. 작은 콘텐츠로 이 정책을 테스트하려면 thresholdKb를 1024보다 훨씬 작은 값으로 설정하세요.

`warn-package-publish`

이벤트: PreToolUse (Bash)
기본값: npm publish 실행 전 Claude에게 확인하도록 지시합니다. 파라미터 없음.

`warn-background-process`

이벤트: PreToolUse (Bash)
기본값: nohup, &, disown, screen을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의를 기울이도록 지시합니다. 파라미터 없음.

`warn-global-package-install`

이벤트: PreToolUse (Bash)
기본값: 가상 환경 없이 npm install -g, yarn global add, pip install 실행 전 Claude에게 확인하도록 지시합니다. 파라미터 없음.

패키지 매니저

에이전트가 사용할 수 있는 패키지 매니저를 강제합니다.

`prefer-package-manager`

이벤트: PreToolUse (Bash)
기본값: 비활성화. 활성화되면 allowed 목록에 없는 패키지 매니저 명령을 차단하고 Claude에게 허용된 매니저를 사용하도록 명령을 재작성하도록 지시합니다. 감지 대상: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.

파라미터	타입	기본값	설명
`allowed`	string[]	`[]`	허용된 패키지 매니저 이름. 목록에 없는 감지된 매니저는 차단됩니다. 비어있으면 정책은 아무 작업도 하지 않습니다.
`blocked`	string[]	`[]`	기본 제공 목록 외에 추가로 차단할 매니저 이름(예: `['pdm', 'pipx']`).

기본 제공 차단 목록: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. blocked를 사용하여 이 목록에 없는 매니저를 추가합니다. 예시 설정:

{
  "enabledPolicies": ["prefer-package-manager"],
  "policyParams": {
    "prefer-package-manager": {
      "allowed": ["uv", "bun"],
      "blocked": ["pdm", "pipx"]
    }
  }
}

이 설정으로 pip install flask와 pdm install flask는 모두 차단되며 Claude에게 uv 또는 bun을 사용하라는 메시지가 표시됩니다. uv pip install flask와 같은 명령은 uv가 허용 목록에 있고 먼저 확인되므로 허용됩니다.

AI 동작

에이전트가 막히거나 예상치 못한 동작을 할 때 감지합니다.

`warn-repeated-tool-calls`

이벤트: PreToolUse (모든 도구)
기본값: 동일한 도구가 동일한 파라미터로 3회 이상 호출될 때 Claude에게 재고하도록 지시합니다. 이는 에이전트가 루프에 빠진 일반적인 징후입니다. 파라미터 없음.

워크플로

체계적인 세션 종료 워크플로를 강제합니다. 이러한 정책은 Stop 이벤트에서 실행되며 각 조건이 충족될 때까지 에이전트의 중단을 차단합니다. 자연스러운 의존성 체인을 따릅니다: 커밋 → 푸시 → PR → CI. 정책이 차단하면 체인의 후속 정책은 건너뜁니다(deny 단락 평가). 모든 워크플로 정책은 fail-open입니다: 필요한 도구를 사용할 수 없는 경우(예: gh가 설치되지 않음, git 원격 없음), 정책은 확인이 건너뛰어진 이유를 설명하는 안내 메시지와 함께 허용합니다.

CLI별 Stop 동작 방식

Stop 적용은 일곱 가지 지원 CLI에서 각각 다른 “에이전트 완료” 훅 계약을 노출하기 때문에 약간 다르게 보입니다. 결과는 동일합니다 — 에이전트는 워크플로 게이트가 실패하는 동안 중단될 수 없습니다 — 하지만 메커니즘은 다릅니다. 아래 표는 요약을 제공합니다. Pi만 require-*-before-stop 정책을 활성화하기 전에 이해할 가치가 있는 사용자에게 보이는 동작 방식의 특이점이 있습니다.

CLI	게이트 실행 시점	표시되는 내용
Claude Code	동일한 에이전트 루프, 즉시	Claude가 계속 작동합니다 — 문제를 수정한 다음 다시 완료를 시도합니다. 사용자에게 중단이 보이지 않습니다.
Codex	동일한 에이전트 루프, 즉시	Claude와 동일합니다.
GitHub Copilot CLI	동일한 에이전트 루프, 즉시	Claude와 동일합니다(Copilot의 `{decision:"block", reason}` 재시도 채널 사용 — Copilot CLI 1.0.41에 대해 경험적으로 검증됨).
Cursor Agent	동일한 에이전트 루프, 즉시	Claude와 동일합니다(Cursor의 `{followup_message}` 채널 사용 — `loop_limit`에 의해 제한, 기본 5회 재시도).
Gemini CLI	동일한 에이전트 루프, 즉시	Claude와 동일합니다(`AfterAgent`의 Gemini `{decision:"block", reason}` 채널 사용).
OpenCode	동일한 에이전트 루프, 즉시	Claude와 동일합니다(`hookSpecificOutput.additionalContext`를 통해 라우팅된 OpenCode의 `client.session.prompt(...)` SDK 호출 사용).
Pi (pi-coding-agent)	다음 사용자 턴	Pi는 게이트가 실행될 때 눈에 띄게 중단됩니다 — 에이전트 루프가 종료되고 프롬프트로 반환됩니다. 그런 다음 다음에 프롬프트를 제출할 때 게이트가 실행됩니다: failproofai는 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여 LLM에게 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 지시합니다.

Pi의 제한 사항. Pi의 AgentEndEvent(Claude의 Stop 훅에 해당하는 업스트림 이벤트)에는 Result 타입이 없습니다 — 실행될 때 Pi의 에이전트 루프가 이미 종료된 상태입니다. Pi는 Claude / Copilot / Cursor / Gemini / OpenCode처럼 동일한 루프를 강제로 재시도할 수 없습니다. failproofai는 게이트를 Pi의 before_agent_start 이벤트(다음 사용자 프롬프트 이후에 실행됨)로 이동하여 워크플로 확인이 여전히 적용되도록 합니다. 단, 현재 턴이 아닌 다음 턴에 적용됩니다.실제로 이것이 의미하는 바:

Pi가 중단된 후, deny 이유는 Pi 세션 id로 키잉된 인메모리에 캡처됩니다. 동일한 Pi 프로세스에서 제출하는 바로 다음 프롬프트가 이를 소비합니다: LLM은 시스템 프롬프트 상단에 MANDATORY ACTION REQUIRED 지시문을 보고, 커밋(또는 푸시 / PR 열기 / CI 대기)한 다음 요청을 계속합니다. 캡처된 deny 이유는 한 번만 소비됩니다 — 소비되면 게이트가 해제됩니다.
게이트는 Pi의 프로세스 수명에 의해 제한됩니다. 턴 사이에 Pi를 Ctrl+C하거나 종료하면 인메모리 항목이 프로세스와 함께 삭제되고 게이트를 놓치게 됩니다. Claude, Copilot, Cursor, Gemini, OpenCode도 동일한 제한이 있습니다(에이전트를 종료하면 게이트를 놓침) — Pi는 에이전트가 게이트 실행 전에 눈에 띄게 종료되기 때문에 이를 더 분명하게 만들 뿐입니다.
보류 중인 deny는 어떤 이유로든 session_shutdown(new / resume / fork / quit) 시 지워지므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출될 수 없습니다.

Claude 스타일의 동일 루프 재시도가 필요하다면, 다른 여섯 가지 지원 CLI 중 하나에서 Stop 정책을 실행하세요. Pi 업스트림에서 이 격차를 해소할 수 있는 AgentEndEvent의 향후 Result 타입을 추적하고 있습니다.

`require-commit-before-stop`

이벤트: Stop
기본값: 커밋되지 않은 변경 사항(수정, 스테이징, 추적되지 않은 파일)이 있을 때 중단을 차단합니다. 작업 디렉토리가 깨끗할 때 안내 메시지를 반환합니다. 파라미터 없음.

`require-push-before-stop`

이벤트: Stop
기본값: 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 중단을 차단합니다. 필요한 경우 git push -u를 통해 추적 브랜치를 생성하도록 제안합니다. 원격이 구성되지 않은 경우 fail-open됩니다. 파라미터:

파라미터	타입	기본값	설명
`remote`	`string`	`"origin"`	푸시할 원격 이름.

예시:

{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}

`require-pr-before-stop`

이벤트: Stop
기본값: 현재 브랜치에 풀 리퀘스트가 없거나 기존 PR이 병합 없이 닫힌 경우 중단을 차단합니다. Claude에게 gh pr create로 PR을 생성하도록 지시합니다. PR이 병합되면 정책은 허용하고(작업이 배포됨) 브랜치에서 전환하도록 힌트를 제공합니다(git checkout main && git pull). 파라미터 없음.

이 정책은 GitHub CLI(gh)가 설치되고 인증된 상태를 요구합니다. 풀 리퀘스트에 대한 읽기 접근을 위해 repo 스코프가 있는 개인 액세스 토큰으로 gh auth login을 실행하세요. gh가 설치되지 않았거나 인증되지 않은 경우, 정책은 fail-open되고 Claude에게 이유를 보고합니다.

`require-no-conflicts-before-stop`

이벤트: Stop
기본값: 현재 브랜치가 베이스 브랜치에 깔끔하게 병합될 수 없을 때 중단을 차단합니다. 정책은 먼저 브랜치에 대한 GitHub의 OPEN PR이 있는지 확인합니다 — PR이 없으면 적용할 병합 대상이 없으므로 전체 정책이 단락 평가되어 허용됩니다. OPEN PR이 확인되면 두 가지 독립적인 검사가 실행됩니다:

로컬 — git merge-tree --write-tree --name-only origin/<baseBranch> HEAD. 충돌 시, deny 메시지에 충돌 파일 이름을 표시하여 Claude가 무엇을 해결해야 하는지 정확히 알 수 있습니다.
GitHub — 사전 확인에서 이미 가져온 gh pr view --json mergeable,state 결과를 재사용합니다. 오래된 로컬 origin/<baseBranch>가 놓칠 수 있는 충돌을 감지합니다(예: 마지막 fetch 이후 누군가가 충돌하는 PR을 main에 병합한 경우). CONFLICTING 결과는 차단됩니다. UNKNOWN 결과도 차단되며 Claude에게 다시 중단을 시도하기 전에 약 10초 대기하고 재확인하도록 지시합니다 — 이는 GitHub가 재계산하는 동안 거짓 음성을 방지합니다.

다음의 경우 완전히 건너뜁니다(허용): gh가 설치되지 않음, 브랜치에 PR이 없음, PR 상태가 OPEN이 아님(예: MERGED, CLOSED), 또는 gh pr view가 파싱 불가능한 출력을 반환함. 로컬에 origin/<baseBranch>가 없거나 베이스보다 앞선 커밋이 없는 경우에도 fail-open됩니다 — 이러한 레이어 1 폴스루는 허용하기 전에 캐시된 PR 병합 가능성을 여전히 참조합니다. 파라미터:

파라미터	타입	기본값	설명
`baseBranch`	`string`	`"main"`	충돌을 확인할 베이스 브랜치.

이 정책에는 GitHub CLI(gh)가 필요합니다. 정책은 충돌 검사를 실행하기 전에 gh pr view를 사용하여 OPEN PR이 있는지 확인합니다 — gh 없이는 정책이 단락 평가되어 허용됩니다. 풀 리퀘스트에 대한 읽기 접근을 위해 repo 스코프가 있는 개인 액세스 토큰으로 gh auth login을 실행하세요.

`require-ci-green-before-stop`

이벤트: Stop
기본값: 현재 브랜치의 CI 검사가 실패하거나 실행 중일 때 중단을 차단합니다. GitHub Actions 워크플로 실행과 서드파티 봇 검사(예: CodeRabbit, SonarCloud, Codecov)를 모두 확인합니다. skipped, cancelled, neutral 결론은 실패로 처리하지 않습니다(후자는 예를 들어 외부 기여자 PR에서의 Socket Security 알림을 포함합니다. 여기서 앱은 의도적으로 성공/실패 대신 neutral을 보고합니다). 모든 검사가 통과되면 안내 메시지를 반환합니다. 파라미터 없음.

이 정책은 GitHub CLI(gh)가 설치되고 인증된 상태를 요구합니다. Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위해 repo 스코프가 있는 개인 액세스 토큰으로 gh auth login을 실행하세요. gh가 설치되지 않았거나 인증되지 않은 경우, 정책은 fail-open되고 Claude에게 이유를 보고합니다.

개별 정책 비활성화

설정의 enabledPolicies에서 특정 정책을 제거하거나 대시보드의 Policies 탭에서 비활성화하세요.

{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}

enabledPolicies에 나열되지 않은 정책은 policyParams 항목이 있더라도 실행되지 않습니다.

​개요

​네임스페이스

​위험한 명령어

​block-sudo

​block-rm-rf

​block-curl-pipe-sh

​block-failproofai-commands

​인프라 명령어

​block-kubectl

​block-terraform

​block-aws-cli

​block-gcloud

​block-az-cli

​block-helm

​block-gh-pipeline

​시크릿(새니타이저)

​sanitize-jwt

​sanitize-api-keys

​sanitize-connection-strings

​sanitize-private-key-content

​sanitize-bearer-tokens

​환경

​block-env-files

​protect-env-vars

​파일 접근

​block-read-outside-cwd

​block-secrets-write

​Git

​block-push-master

​block-work-on-main

​block-force-push

​warn-git-amend

​warn-git-stash-drop

​warn-all-files-staged

​데이터베이스

​warn-destructive-sql

​warn-schema-alteration

​경고

​warn-large-file-write

​warn-package-publish

​warn-background-process

​warn-global-package-install

​패키지 매니저

​prefer-package-manager

​AI 동작

​warn-repeated-tool-calls

​워크플로

​CLI별 Stop 동작 방식

​require-commit-before-stop

​require-push-before-stop

​require-pr-before-stop

​require-no-conflicts-before-stop

​require-ci-green-before-stop

​개별 정책 비활성화

개요

네임스페이스

위험한 명령어

`block-sudo`

`block-rm-rf`

`block-curl-pipe-sh`

`block-failproofai-commands`

인프라 명령어

`block-kubectl`

`block-terraform`

`block-aws-cli`

`block-gcloud`

`block-az-cli`

`block-helm`

`block-gh-pipeline`

시크릿(새니타이저)

`sanitize-jwt`

`sanitize-api-keys`

`sanitize-connection-strings`

`sanitize-private-key-content`

`sanitize-bearer-tokens`

환경

`block-env-files`

`protect-env-vars`

파일 접근

`block-read-outside-cwd`

`block-secrets-write`

Git

`block-push-master`

`block-work-on-main`

`block-force-push`

`warn-git-amend`

`warn-git-stash-drop`

`warn-all-files-staged`

데이터베이스

`warn-destructive-sql`

`warn-schema-alteration`

경고

`warn-large-file-write`

`warn-package-publish`

`warn-background-process`

`warn-global-package-install`

패키지 매니저

`prefer-package-manager`

AI 동작

`warn-repeated-tool-calls`

워크플로

CLI별 Stop 동작 방식

`require-commit-before-stop`

`require-push-before-stop`

`require-pr-before-stop`

`require-no-conflicts-before-stop`

`require-ci-green-before-stop`

개별 정책 비활성화