Permission System Design

도구 호출 평가 순서 (결정론적, 첫 매칭 승리):

1. deny 규칙 → 매칭되면 즉시 차단
2. ask 규칙 → 매칭되면 사용자에게 확인 요청
3. allow 규칙 → 매칭되면 자동 허가
4. defaultMode → 위 중 아무것도 없으면 기본 동작

Specificity는 순서를 이기지 않는다. deny ["Bash(*)"]와 allow ["Bash(npm run test)"]가 동시에 있으면, allow가 더 구체적이라도 deny가 이긴다. 이것을 모르면 의도치 않은 차단이 발생한다.

설정 파일 우선순위 (높은 것 → 낮은 것):

1. Managed settings (조직 배포, 오버라이드 불가)
2. CLI arguments (--allowedTools, --disallowedTools)
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

중요: 어느 레벨에서든 도구가 deny되면 다른 레벨에서 allow할 수 없다.

bypassPermissions 경고: 이 모드는 반드시 컨테이너나 VM 안에서만 사용해야 한다. 베어 호스트 OS에서 bypassPermissions를 사용하는 것은 지금까지 발생한 주요 사고들의 공통 원인이다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",           // npm run으로 시작하는 모든 명령
      "Bash(git commit *)",        // git commit 허용
      "Bash(* --version)",         // --version 플래그 가진 모든 명령
      "Read(./.env)",              // 특정 .env 파일 읽기 허용
      "WebFetch(domain:github.com)",// github.com 도메인만
      "WebFetch(domain:*.example.com)",// 서브도메인 포함
      "mcp__puppeteer__*",         // puppeteer MCP 모든 도구
      "Agent(Explore)"             // Explore 서브에이전트 타입
    ],
    "deny": [
      "Bash(git push --force *)",   // force push 금지
      "Bash(rm -rf *)",            // 재귀 삭제 금지
      "Read(~/.ssh/*)",            // SSH 키 읽기 금지
      "Read(.env*)",               // .env 파일 읽기 금지
      "mcp__*"                     // 모든 MCP 도구 금지
    ],
    "ask": [
      "Bash(git push *)",          // push는 확인 요청
      "Bash(terraform apply *)",   // terraform apply 확인
      "Bash(rm *)",               // rm은 확인
      "Bash(git reset --hard *)"
    ]
  }
}

중요 문법 규칙:

• 공백이 중요: Bash(ls *) = ls 뒤에 공백+인수. Bash(ls*) = ls로 시작하는 것 (lsof 포함)
• 복합 명령 (&&, ||, ;, |): 각 서브명령이 독립적으로 평가됨
• 프로세스 래퍼(timeout, nice, nohup 등)는 매칭 전 제거됨
• 읽기 전용 명령(ls, cat, grep, find 등)은 자동 승인

Pattern A: Approval-First (프로덕션 저장소)

{
  "permissions": {
    "ask": ["Bash(*)", "Write(*)"],
    "deny": ["Bash(rm -rf *)", "Bash(git push --force *)", "Bash(sudo *)"],
    "defaultMode": "dontAsk"
  }
}

• 가장 작은 blast radius
• 프로덕션 자격증명, 공유 인프라에 적합

Pattern B: Curated Allow-List (팀/개인 프로젝트)

{
  "permissions": {
    "allow": ["Read(*)", "Bash(npm run *)", "Bash(git status)", "Bash(git log *)", "Bash(git commit *)", "Bash(git diff *)"],
    "ask": ["Bash(git push *)", "Bash(git reset *)"],
    "deny": ["Bash(git push --force *)", "Bash(rm -rf *)"]
  }
}

• 속도와 안전의 균형
• 일반 개발 팀에 권장

Pattern C: Sandboxed Full-Auto (배치 작업) — 컨테이너 필수!

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

FROM debian:stable-slim
RUN useradd --create-home claudebot
USER claudebot  # 절대 root로 실행 금지
WORKDIR /workspace
# ~/.ssh, ~/.aws, ~/.config 마운트 절대 금지