Claude Code 2.1.178의 권한 규칙은 도구 인자(Argument)까지 매칭할 수 있다

지금까지 Claude Code의 권한 규칙은 커맨드 문자열과 파일 경로만을 보고 있었다. Bash(npm run test *)와 같이 "무엇을 실행할 것인가"를 문자열로 허용하거나 거부하는 방식이었으며, 이는 그 자체로 강력했다. 하지만 도구에 따라서는 "무엇을 전달할 것인가"가 구조화된 인자(Argument)로 결정되어 있는 경우가 있다. 대표적인 예가 Agent 도구인데, 여기에는 model이라는 인자가 있다. 서브 에이전트(Sub-agent)를 Opus로 실행할지 Haiku로 실행할지는 커맨드 문자열 어디에도 나타나지 않는다. 따라서 기존 방식으로는 "서브 에이전트에게 Opus를 사용하지 못하게 한다"라는 규칙을 작성할 수 없었다.

6월 15일 v2.1.178에서 그 빈틈이 메워졌다. changelog의 한 문장이 모든 것을 말해주고 있다.

Added Tool(param:value) syntax for permission rules to match a tool's input parameters (with * wildcard)

Claude Code changelog에서 발췌. 예시로 들어있는 것이 Agent(model:opus)이며, 이를 deny에 두면 Opus 서브 에이전트 기동만을 핀포인트로 차단할 수 있다.

작성 방법은 기존의 권한 규칙과 동일하게 settings.json의 permissions 블록에 추가하기만 하면 된다. allow에 넣으면 자동 승인, deny에 넣으면 차단, ask에 넣으면 매번 확인하게 된다.

{
"permissions": {
"deny": [
...

포인트는 매칭 대상이 커맨드 라인이 아니라 도구로의 입력 인자 그 자체라는 점이다. param:value 형태로 인자 이름과 값을 지정하며, 값에는 * 와일드카드(Wildcard)를 사용할 수 있다. 예를 들어 claude-opus로 시작하는 모델을 한꺼번에 거부하고 싶다면 다음과 같이 쓸 수 있다(값의 와일드카드는 공식적으로 명시된 동작이다).

{
"permissions": {
"deny": [
...

사실 이 "인자로 대조한다"는 발상 자체가 완전히 새로운 것은 아니다. 조금 전 v2.1.176에서는 WebFetch(domain:*.example.com)의 서브도메인 대조 버그 수정이 포함되어 있었기에, domain:이라는 인자 지정은 이미 작동하고 있었다. 이번 변경은 그것을 특정 도구의 특권 패턴에서 임의의 도구 입력 인자로 일반화한 것으로 읽을 수 있다. WebFetch의 도메인 제한과 Agent의 모델 제한을 동일한 문법으로 작성할 수 있게 되었다는 정리다.

솔직히 말하면, 이 규칙 단독으로는 "유용한 팁" 정도로 끝난다. 진가를 발휘하는 것은 직전의 v2.1.172와 조합했을 때다. 이 버전에서 서브 에이전트가 스스로 서브 에이전트를 생성할 수 있게 되었다. 최대 5계층의 중첩(Nest)이 가능하다.

Added: Sub-agents can now spawn their own sub-agents (up to 5 levels deep)

에이전트가 트리 구조로 증식하는 세계에서는, 말단의 서브 에이전트가 어떤 모델로 동작하고 있는지를 인간이 일일이 파악하는 것은 현실적이지 않다. 5계층 깊은 곳에서 실수로 전부 Opus가 기동되어 있었다는 상황은 비용 측면에서도, 동작의 예측 가능성 측면에서도 두렵다. 여기서 Agent(model:...)와 같은 인자 매칭이 증식하는 트리 전체에 적용되는 가드레일(Guardrail)이 된다. 문자열 allowlist였던 것이 구조화된 정책(Policy)에 한 걸음 다가갔다는 것이 나의 견해다. R&D에서 에이전트 병렬 처리를 돌리다 보면, 멈추고 싶은 것은 "특정 커맨드"가 아니라 "특정 행동"인 경우가 많다. 인자 매칭은 비로소 그 입도(Granularity)에 도달했다.

조직에서 배포한다면 더 상위 레이어가 있다. v2.1.175에서 도입된 enforceAvailableModels는 availableModels 허용 리스트로 Default 모델까지 제어하는 managed 설정이다. 여기에 더해 allowManagedPermissionRulesOnly를 사용하면, 사용자 설정이나 프로젝트 설정이 allow / ask / deny...

자체적으로 allow / ask / deny... 등을 정의하는 것을 금지하고, managed 설정의 규칙만 활성화할 수 있게 합니다 (모두 settings 문서에 기재되어 있음). 인자 매칭 (Argument matching)의 새로운 문법은 이러한 통제 메커니즘의 표현력을 그대로 끌어올립니다. 즉, "이 리포지토리에서는 서브 에이전트(Sub-agent)에게 Opus를 사용하게 하지 않는다"라는 규칙을 개인이 덮어쓸 수 없는 형태로 배포할 수 있다는 의미입니다.

버전	날짜	관련 변경 사항
v2.1.172	6/10	서브 에이전트 중첩 (최대 5계층)
v2.1.175	6/12	enforceAvailableModels를 통해 Default 모델을 허용 리스트로 제한
v2.1.178	6/15	Tool(param:value) 인자 매칭 (Argument matching), Agent(model:opus)

직접 적용해 보려면, 우선 적용하고자 하는 도구(Tool)의 인자(Argument) 이름을 정확히 알 필요가 있습니다. Agent의 model과 같이, 규칙에 작성하는 키(Key)는 도구가 실제로 받는 입력 파라미터(Parameter) 이름과 일치하지 않으면 그대로 통과되어 버립니다. 커맨드 문자열을 다룰 때와 같은 "대략적인 전방 일치 (Prefix match)" 느낌으로 작성하면, 차단하려고 했는데 차단되지 않는 사고가 발생하기 쉬운 부분입니다. 배포 전에 실제로 해당 모델로 서브 에이전트를 실행시켜 차단되는지 한 번 확인해 볼 것을 권장합니다.

기능 자체는 눈에 띄지 않지만, 에이전트가 다층화되어 가는 흐름 속에서는 이러한 "행위 그 자체를 선언적 (Declarative)으로 제한할 수 있는" 프리미티브 (Primitive)가 효과를 발휘합니다. 1차 정보는 공식 changelog에 정리되어 있습니다.