Claude Code 권한 규칙, 도구보다 입력값이 위험하다

AI 코딩 에이전트 운영에서 가장 위험한 착각은 “도구를 허용했는가, 막았는가”만 보면 충분하다고 믿는 것이다. Claude Code v2.1.178의 Tool(param:value) 권한 규칙은 이 기준을 흔든다. 이제 Claude Code 권한 규칙을 봐야 하는 이유는 에이전트가 어떤 도구를 쓰는지보다 어떤 입력값, 어떤 모델, 어떤 하위 에이전트로 실행되는지가 비용과 보안의 실제 경계가 되기 때문이다.

 

 

내가 보기엔 이번 변화의 핵심은 기능 하나가 추가됐다는 데 있지 않다. 코딩 에이전트를 운영하는 정책의 단위가 바뀌었다. 예전에는 “Bash를 허용할 것인가”, “Agent를 허용할 것인가”, “MCP 도구를 쓸 수 있게 할 것인가”가 질문이었다. 이제 질문은 더 날카로워진다. “어떤 Bash 호출인가”, “어떤 Agent 호출인가”, “어떤 모델로 subagent를 띄우는가”, “어떤 MCP 서버와 도구 조합을 허용할 것인가”가 운영 기준이 된다.

v2.1.178에서 바뀐 것

Claude Code v2.1.178 릴리스 노트에는 권한 규칙에서 Tool(param:value) 문법을 지원한다는 내용이 들어갔다. 함께 언급된 예시는 * wildcard와 Agent(model:opus) 형태다. 이 문법은 단순히 도구 이름만 적는 방식에서 한 단계 더 들어가, 도구 호출의 특정 specifier나 파라미터 조건을 권한 정책에 반영할 수 있다는 방향을 보여준다.

 

다만 여기서 과장하면 안 된다. 공식 문서의 permissions 설명은 Tool 또는 Tool(specifier) 형식을 설명하고, allow, ask, deny 정책을 다룬다. 하지만 릴리스 노트에 나온 Agent(model:opus) 같은 세부 기능이 문서 전체에 완전히 같은 깊이로 반영되어 있다고 보기는 어렵다. 따라서 이 글에서는 이를 “릴리스 노트 기준 신규 기능”으로 다룬다. 모든 도구의 모든 파라미터가 동일하게 통제된다고 단정하지 않는다.

 

같은 릴리스에는 nested .claude/skills 로딩 개선, nearest working directory의 agent/workflow/output-style 우선 적용, auto mode classifier 개선, subagent disallowedTools의 MCP server-level specs 관련 버그 수정도 포함됐다. 이 변화들은 따로 떨어진 편의 기능처럼 보이지만, 실제로는 같은 방향을 가리킨다. Claude Code는 점점 더 “프로젝트 가까이에 있는 설정”, “세분화된 에이전트 역할”, “도구 호출의 더 구체적인 조건”을 기준으로 움직이는 쪽으로 가고 있다.

도구 이름만으로는 정책이 부족하다

기존의 단순한 allow/deny 목록은 이해하기 쉽다. 예를 들어 Bash를 허용하거나 막고, Agent를 허용하거나 막고, 특정 MCP 도구를 허용하거나 막는 식이다. 문제는 실제 위험이 도구 이름에만 있지 않다는 점이다.

 

Bash라는 이름 하나 안에는 안전한 ls, 비교적 무해한 npm test, 위험한 rm -rf, 더 위험한 배포 명령, 데이터베이스 마이그레이션 명령이 함께 들어간다. Agent 역시 마찬가지다. 어떤 subagent를 부르는지, 어떤 모델로 부르는지, 어떤 도구 권한을 가진 subagent인지에 따라 비용과 위험이 달라진다. MCP도 단순히 “GitHub MCP 허용”으로 끝나지 않는다. 이슈 조회와 PR 수정, secret 접근, 배포 파이프라인 트리거는 완전히 다른 등급의 작업이다.

 

내 판단은 명확하다. 에이전트 보안의 단위는 도구 이름에서 도구 호출 입력값으로 내려가야 한다. 도구 이름은 너무 크고, 실제 사고는 그 안의 특정 호출에서 난다. Tool(param:value) 문법이 중요한 이유가 여기에 있다. 운영자는 이제 “이 도구는 된다/안 된다”가 아니라 “이 조건의 호출은 된다/안 된다/물어봐야 한다”로 정책을 설계해야 한다.

deny, ask, allow 순서를 운영 언어로 이해해야 한다

Claude Code permissions 문서에서 중요한 부분은 평가 순서다. 권한 규칙은 deny, ask, allow 순서로 평가된다. 이 말은 운영 정책에서 “명시적 금지”가 가장 강한 경계가 된다는 뜻이다. 먼저 절대 하면 안 되는 호출을 잡고, 그다음 확인이 필요한 호출을 ask로 두고, 마지막으로 반복 가능한 안전 작업만 allow로 열어야 한다.

 

여기서 bare tool deny와 scoped rule의 차이도 중요하다. 도구 전체를 deny하면 그 도구에 대한 더 좁은 허용 규칙을 기대하기 어렵다. 반대로 scoped rule은 특정 범위나 specifier를 기준으로 더 세밀한 정책을 만들기 위한 방식이다. 실제 운영에서는 “도구 전체 차단”과 “특정 호출 차단”을 구분해야 한다. 무조건 크게 막으면 생산성이 죽고, 무조건 크게 열면 자동화가 사고로 이어진다.

보수적인 정책 설계 순서

실무에서는 다음 순서가 낫다.

• 먼저 절대 금지할 작업을 정한다. 예: 프로덕션 배포, destructive shell command, secret 출력, 운영 DB 변경.
• 다음으로 승인 후 실행할 작업을 정한다. 예: 패키지 설치, 파일 대량 변경, 외부 시스템 쓰기, 고비용 모델 호출.
• 마지막으로 자동 허용할 작업을 정한다. 예: 읽기, 검색, 테스트 실행, 특정 안전 범위의 로컬 파일 수정.
• MCP 서버와 subagent는 도구 이름이 아니라 역할, 접근 범위, 부작용 기준으로 분류한다.
• 모델 선택은 품질 문제가 아니라 비용 정책이기도 하므로 권한 정책 안에서 다룬다.

이 순서를 지키면 권한 설정은 단순한 설정 파일이 아니라 자동화 운영 정책이 된다.

비용 통제와 보안 통제가 같은 문법 안으로 들어온다

Agent(model:opus) 예시가 흥미로운 이유는 보안만의 문제가 아니기 때문이다. 모델 선택은 곧 비용, 지연 시간, 품질, 위험 허용 범위의 선택이다. 고성능 모델은 어려운 작업에 유용하지만 모든 자동 실행 경로에서 기본값처럼 쓰이면 비용 폭탄이 된다. 특히 subagent가 내부적으로 여러 번 호출되는 워크플로우에서는 모델 선택 하나가 전체 비용 구조를 바꾼다.

 

내가 보기엔 Claude Code 권한 규칙의 다음 운영 포인트는 “고비용 모델을 언제 허용할 것인가”다. 예를 들어 일반 코드 검색, 간단한 리팩터링, 테스트 실패 원인 요약은 저비용 모델이나 기본 모델로 충분할 수 있다. 반대로 대규모 아키텍처 변경, 복잡한 보안 리뷰, 실패한 마이그레이션 분석은 더 강한 모델을 ask 또는 제한적 allow로 둘 수 있다. 중요한 것은 모델 선택을 프롬프트 예절에 맡기지 않는 것이다.

 

“가능하면 비싼 모델 쓰지 마” 같은 지시는 약하다. 설정과 권한 규칙으로 경계를 만드는 편이 강하다. Claude Code settings 문서가 다루는 permissions, settings scope, managed settings, availableModels 같은 항목은 그래서 중요하다. 개인 설정, 프로젝트 설정, 관리형 설정이 섞이면 누가 어떤 범위에서 무엇을 바꿀 수 있는지도 운영 이슈가 된다.

프롬프트보다 강한 경계가 필요하다

AI 자동화 운영에서 흔한 실수는 위험한 작업을 프롬프트 주의사항으로만 막으려는 것이다. “절대 삭제하지 마”, “배포하지 마”, “민감 정보는 읽지 마” 같은 문장은 필요하지만 충분하지 않다. 모델은 문장을 해석하고, 도구는 실제로 실행한다. 사고를 막는 경계는 프롬프트보다 실행 계층에 가까울수록 강하다.

 

Claude Code에서 그 경계는 settings.json, permissions, managed settings, hooks, sandboxing, 그리고 MCP와 subagent의 권한 설계에 있다. permissions는 어떤 도구 호출을 허용할지 묻는다. managed settings는 조직이나 팀 차원의 기본 경계를 만들 수 있다. hooks는 실행 전후에 검증이나 차단 로직을 넣을 수 있다. sandboxing은 실행 환경 자체를 제한하는 방향이다. 이 조합이 프롬프트보다 강한 운영 경계다.

 

물론 이것도 완벽한 보안은 아니다. Bash 패턴을 조금 정교하게 쓴다고 해서 shell 실행의 모든 위험이 사라지지 않는다. MCP 도구를 제한한다고 해서 외부 시스템의 권한 설계가 자동으로 안전해지는 것도 아니다. subagent를 나눈다고 해서 책임 경계가 저절로 생기지도 않는다. 다만 프롬프트 하나에 기대는 것보다 훨씬 검증 가능한 정책이 된다.

subagent와 MCP는 별도 권한 영역으로 봐야 한다

Claude Code docs는 Agent(AgentName) 형태로 subagent 제어를 설명한다. subagent는 단순한 프롬프트 조각이 아니다. 특정 역할, 별도 컨텍스트, 별도 도구 사용 범위를 가진 실행 단위에 가깝다. 그래서 “Agent 허용”은 생각보다 큰 결정이다. 어떤 subagent가 어떤 도구를 들고 움직이는지 모르면, 메인 에이전트보다 더 넓은 우회 경로가 생길 수 있다.

 

이번 릴리스의 subagent disallowedTools MCP server-level specs 버그 수정도 이 맥락에서 봐야 한다. MCP 서버 단위, 도구 단위, subagent 단위의 권한이 서로 맞물릴 때 작은 해석 차이가 실제 운영에서는 크게 번진다. 특히 사내 GitHub, 이슈 트래커, 문서 검색, 배포 시스템, 데이터베이스 조회 도구를 MCP로 붙여둔 팀이라면 권한 규칙을 “Claude Code 설정”이 아니라 “내부 시스템 접근 정책”으로 봐야 한다.

실무에서 나눠야 할 등급

MCP와 subagent를 운영할 때는 최소한 다음 등급으로 나눠야 한다.

• 읽기 전용: 검색, 문서 조회, 코드베이스 탐색, 이슈 목록 확인.
• 제한적 쓰기: PR 코멘트 작성, 임시 브랜치 수정, 테스트용 파일 생성.
• 고위험 쓰기: main 브랜치 변경, 릴리스 생성, 배포 트리거, 운영 데이터 변경.
• 비용 민감 호출: 고성능 모델 subagent, 장시간 분석, 반복적 멀티 에이전트 워크플로우.
• 보안 민감 호출: secret, private repo, 내부 문서, 고객 데이터와 맞닿은 도구.

이 분류 없이 “MCP 허용”, “Agent 허용”으로 끝내면 자동화는 빠르지만 통제 불가능해진다.

설정 예시는 보수적으로만 복사해야 한다

권한 설정 예시는 항상 조심해야 한다. 공식 문서와 릴리스 노트의 구조를 참고하되, 아직 문서화가 충분하지 않은 세부 문법을 운영 환경에 그대로 복사하는 것은 위험하다. 특히 Agent(model:opus)는 릴리스 노트 기준으로 언급된 신규 기능으로 보는 것이 안전하다. 실제 프로젝트에 적용하기 전에는 현재 설치된 Claude Code 버전, 공식 docs, 팀의 managed settings와 충돌 여부를 확인해야 한다.

 

보수적인 pseudo 예시는 이런 식으로 생각할 수 있다. 실제 설정 파일에 그대로 붙여넣으라는 뜻이 아니라 정책 구조를 설명하기 위한 예시다.

{
  "permissions": {
    "deny": [
      "Bash(rm:*)",
      "Agent(HighRiskDeploymentAgent)"
    ],
    "ask": [
      "Agent(model:opus)",
      "Bash(npm:install)"
    ],
    "allow": [
      "Read(*)",
      "Grep(*)"
    ]
  }
}

이 예시는 일부러 보수적으로 썼다. 핵심은 정확한 문자열을 외우는 것이 아니라 정책의 방향이다. 위험한 호출은 deny에 먼저 둔다. 비용이 크거나 부작용이 있는 호출은 ask로 둔다. 반복 가능한 읽기와 검색만 allow로 둔다. 그리고 실제 문법과 지원 범위는 반드시 현재 공식 문서와 사용 중인 버전에서 검증해야 한다.

Claude Code 권한 규칙을 운영 정책으로 바꾸는 체크리스트

내 판단은 이번 업데이트 이후 Claude Code 설정을 점검할 때 다음 질문을 반드시 해야 한다는 것이다.

• 지금 allow 목록은 도구 이름 기준인가, 호출 조건 기준인가.
• deny 규칙이 가장 먼저 막아야 할 destructive action을 포함하는가.
• ask 규칙이 고비용 모델, 외부 시스템 쓰기, 패키지 설치, 배포성 명령을 포함하는가.
• Agent 호출은 subagent 이름, 모델, 도구 권한 기준으로 나뉘어 있는가.
• MCP 서버는 읽기 전용, 쓰기 가능, 고위험 쓰기로 분류되어 있는가.
• 프로젝트별 .claude 설정과 상위 설정, managed settings의 우선순위를 이해하고 있는가.
• hooks와 sandboxing으로 권한 규칙 바깥의 실행 경계를 보강했는가.
• Bash 패턴을 보안 만능 장치로 착각하고 있지 않은가.

이 체크리스트를 통과하지 못하면 Claude Code 자동화는 아직 운영 준비가 덜 된 상태다. 코드 생성이 잘 되는 것과 안전하게 운영되는 것은 다른 문제다.

결론: 에이전트는 도구가 아니라 입력값으로 통제된다

Claude Code v2.1.178의 Tool(param:value) 권한 규칙은 작은 문법 변화처럼 보이지만 운영 관점에서는 꽤 크다. 에이전트 통제의 기준이 도구 이름에서 호출 조건으로 내려가고, 모델 선택과 비용 통제가 보안 정책 안으로 들어오기 시작했기 때문이다.

 

내가 보기엔 앞으로의 AI 코딩 에이전트 운영은 “얼마나 많은 도구를 붙였는가”가 아니라 “그 도구를 어떤 입력값과 조건에서만 쓰게 했는가”로 평가될 것이다. Claude Code 권한 규칙은 그 방향을 분명히 보여준다. 프롬프트로 부탁하는 자동화는 약하다. settings, permissions, managed settings, hooks, sandboxing으로 경계를 만든 자동화가 실무에서 오래 간다.

참고자료

• Claude Code v2.1.178 GitHub Release
• GitHub API Release
• Claude Code permissions docs
• Claude Code settings docs
• Claude Code subagents docs
• Claude Code skills docs