기본 제공 정책 - 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에게 반환되기 전에 출력을 검사합니다. 시크릿 패턴이 감지되면 정책은 출력이 다시 전달되지 못하도록 거부 결정을 반환합니다.

`sanitize-jwt`

이벤트: PostToolUse (모든 도구)
기본값: JWT 토큰(.으로 구분된 세 개의 base64url 세그먼트)을 난독화합니다. 매개변수 없음.

`sanitize-api-keys`

이벤트: PostToolUse (모든 도구)
기본값: 일반적인 API 키 형식을 난독화합니다: Anthropic (sk-ant-), OpenAI (sk-), GitHub PATs (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. 정책이 거부하면 체인의 이후 정책은 건너뜁니다 (거부 시 단락). 모든 워크플로 정책은 fail-open 방식입니다: 필요한 도구를 사용할 수 없는 경우(예: gh 미설치, git 리모트 없음) 정책은 확인이 건너뛰어진 이유를 알리는 정보 메시지와 함께 허용합니다.

CLI별 Stop 시맨틱

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

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회 재시도).
OpenCode	동일한 에이전트 루프, 즉시	Claude와 동일 (OpenCode의 `client.session.prompt(...)` SDK 호출을 `hookSpecificOutput.additionalContext`를 통해 라우팅).
Pi (pi-coding-agent)	다음 사용자 턴	Pi는 게이트가 실행될 때 눈에 띄게 중단됩니다 — 에이전트 루프가 종료되고 프롬프트로 돌아옵니다. 그런 다음 다음에 프롬프트를 제출할 때 게이트가 실행됩니다: failproofai는 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여 LLM이 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 안내합니다.

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

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

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

`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이 병합 없이 닫힌 경우 중단을 거부합니다. gh pr create로 PR을 생성하도록 Claude에게 안내합니다. 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이 없으면 강제할 병합 대상이 없으므로 전체 정책이 allow로 단락됩니다. OPEN PR이 확인되면 두 가지 독립적인 프로브가 실행됩니다:

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

다음 경우에 전체 건너뜁니다(허용): gh가 설치되지 않음, 브랜치에 대한 PR이 없음, PR의 상태가 OPEN이 아님 (예: MERGED, CLOSED), 또는 gh pr view가 파싱 불가능한 출력을 반환. origin/<baseBranch>가 로컬에 없거나 베이스보다 앞선 커밋이 없을 때도 fail-open 방식으로 동작합니다 — 이러한 Layer 1 폴스루는 허용하기 전에 캐시된 PR 병합 가능성을 계속 참조합니다. 매개변수:

매개변수	타입	기본값	설명
`baseBranch`	`string`	`"main"`	충돌을 확인할 베이스 브랜치.

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

`require-ci-green-before-stop`

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

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

개별 정책 비활성화

설정 파일의 enabledPolicies에서 특정 정책을 제거하거나, 대시보드의 정책 탭에서 해제하세요.

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

개별 정책 비활성화