잘못 통과된 승인 한 번은 지키려던 파일과 복구에 쓸 시간을 가져갈 수 있다. AI 에이전트에게 셸 명령을 맡기기 시작했다면, 확인창에서 허용을 누를 때마다 범위가 어디까지인지 불안할 만하다. 먼저 확인할 것은 허용 규칙의 범위와 수명, 사람이 답할 수 없는 실행의 처리 방식, 샌드박스의 접근 범위다. 이 글은 그 기준을 Claude Code의 공개 문서로 정리한다.

표지 이미지는 글의 요점을 시각화한 개념 이미지(AI 생성)다.

공식 문서에 따르면 권한 규칙, 훅, 비대화형 실행에는 각각 명시된 판정 조건이 있다. 출처는 Claude Code 권한 문서, 훅 문서, 비대화형 실행 문서이며, 조회일은 모두 2026-09-19다. 아래의 ‘1차 판정’과 ‘2차 검사’는 규칙과 입력 조건을 나누어 읽기 위한 설명 구분이며, 제품 내부 코드의 실행 순서를 뜻하지 않는다.

허용·거부·확인질문, 세 갈래로 갈리는 이유

자동으로 진행할 작업과 막을 작업, 매번 확인할 작업을 나누면 허용 범위를 구체적으로 정할 수 있다. 공식 문서에 따르면 ask 규칙은 지정한 도구를 사용하려 할 때 확인을 요구한다. 규칙은 deny, ask, allow 순서로 평가된다. 출처: 권한 규칙 — 조회일 2026-09-19.

공식 문서에 따르면 내장된 읽기 전용 명령 집합은 읽기 경로 제한에 걸리는 경우를 제외하면 권한 확인 없이 실행된다. 이 명령에도 확인을 요구하려면 ask 규칙을, 차단하려면 deny 규칙을 추가할 수 있다. 따라서 ‘조회처럼 보이는 명령은 모두 자동 허용된다’는 식으로 범위를 넓혀 이해해서는 안 된다. 출처: 읽기 전용 명령과 권한 규칙 — 조회일 2026-09-19.

허용을 누르기 전에 이번 호출의 범위와 그 허용이 유지되는 기간을 확인한다. 도구 이름, 명령 패턴, 저장된 규칙은 구분해서 읽어야 한다.

규칙 문서로 미리 정하는 1차 판정

공식 문서에 따르면 /permissions에서 규칙과 각 규칙의 설정 출처를 확인할 수 있다. 평가는 deny → ask → allow 순서이며 먼저 일치한 규칙이 결과를 정하고, 구체성은 이 순서를 뒤집지 않는다. 넓은 Bash(aws *) deny와 좁은 Bash(aws s3 ls) allow가 함께 맞아도 deny가 이기며, ask와 allow가 함께 맞으면 ask가 우선한다. 출처: 권한 관리와 규칙 우선순위 — 조회일 2026-09-19.

도구 호출이 발생하면 규칙을 deny, ask, allow 순서로 검사한다. 먼저 일치한 규칙이 결과를 정하며, 구체성은 이 순서를 뒤집지 않는다. 그래서 넓은 Bash(aws *) deny와 좁은 Bash(aws s3 ls) allow가 함께 맞아도 deny가 이기고, ask와 allow가 함께 맞으면 ask가 우선한다.
규칙이 얼마나 구체적인지와 상관없이 deny가 ask보다, ask가 allow보다 먼저 결과를 정한다는 점이 핵심이다.

공식 문서에 따르면 Bash 확인창의 ‘다시 묻지 않기’ 승인은 저장되어 같은 저장소의 이후 세션에도 적용될 수 있다. 파일 수정 승인은 세션이 끝날 때까지만 유지된다. 작업 중에도 /permissions를 열 수 있으며, 규칙을 더하거나 빼면 같은 턴의 다음 도구 호출부터 적용된다. 출처: 승인의 수명과 실행 중 규칙 변경 — 조회일 2026-09-19.

이 차이를 고려하면 저장된 허용을 점검할 때도 도구와 적용 범위를 함께 봐야 한다. 한 번의 허용을 모든 도구에 영구 적용되는 결정으로 해석해서는 안 된다. 필요한 명령 패턴을 좁히고, 작업이 달라졌을 때 기존 규칙의 출처와 범위를 확인하는 절차를 권한다.

공식 문서에 따르면 claude -p 비대화형 실행에서 외부 승인 호스트가 없고 규칙·훅·권한 모드로도 승인이 해결되지 않으면, 그 도구 호출은 거부되고 실행은 계속된다. 필요한 범위는 --allowedTools, permissions.allow, 또는 적절한 권한 모드로 미리 승인할 수 있다. --permission-mode acceptEdits는 파일 수정과 일부 파일 시스템 명령을 자동 승인하지만, 읽기 전용 집합 밖의 다른 셸 명령과 네트워크 요청에는 별도 허용이 필요하다. 출처: 비대화형 실행의 권한 처리, 확인창을 표시할 수 없는 세션 — 조회일 2026-09-19.

같은 명령도 내용을 뜯어봐야 하는 2차 검사

공식 문서에 따르면 Bash 규칙은 명령 문자열을 패턴과 대조한다. Bash(npm run build)처럼 정확한 명령을 지정하거나 Bash(npm run test *)처럼 와일드카드로 범위를 정할 수 있다. &&, ||, 세미콜론, 파이프 등으로 묶인 복합 명령은 각 하위 명령이 독립적으로 규칙에 맞아야 한다. 출처: Bash 패턴과 복합 명령 — 조회일 2026-09-19.

허용 규칙만으로 승인할 수 없는 삭제 사례도 문서에 명시돼 있다. 공식 문서에 따르면 중요 경로를 대상으로 하는 rm·rmdir 명령은 allow 규칙이 맞거나 PreToolUse 훅이 허용해도 차단된다. 이는 문서화된 특정 차단기이며, 모든 종류의 위험한 명령을 같은 방식으로 분류한다는 뜻은 아니다. 출처: 어떤 모드도 자동 승인하지 않는 작업 — 조회일 2026-09-19.

공식 문서에 따르면 심볼릭 링크에는 링크 경로와 실제 대상의 비대칭 판정이 적용된다. allow 규칙은 링크와 대상이 모두 일치해야 하며, deny 규칙은 둘 중 하나만 일치해도 차단한다. 허용된 프로젝트 폴더 안의 링크라도 거부된 대상 파일을 가리키면 차단되므로, 표면 경로만으로 접근 범위를 판단해서는 안 된다. 출처: 심볼릭 링크 권한 처리 — 조회일 2026-09-19.

공식 문서에 따르면 PreToolUse 훅은 도구 실행 전에 결정을 반환하거나 도구 입력을 수정할 수 있다. 결정에는 allow, deny, ask, defer가 있지만, defer는 -p 비대화형 실행에서 그 턴에 도구 호출이 하나뿐일 때만 동작한다. 대화형 세션에서는 경고 후 훅 결과가 무시되며, 여러 도구를 동시에 호출한 턴에서도 경고 후 일반 권한 흐름으로 넘어간다. 출처: PreToolUse 결정과 defer 제약 — 조회일 2026-09-19.

공식 문서에 따르면 여러 PreToolUse 훅의 결정이 다르면 우선순위는 deny > defer > ask > allow다. 이는 결정 간 우선순위이며 훅 배열의 실행 순서를 설명하는 규칙은 아니다. 훅이 아무 판단 없이 종료되면 기존 권한 흐름으로 넘어가고, 훅의 allow도 일치하는 deny·ask 권한 규칙을 우회하지 못한다. 출처: 훅 결정 처리, 훅과 권한 규칙의 관계 — 조회일 2026-09-19.

내 운영 기록에는 메인 에이전트가 작성한 훅의 작업 일지가 남아 있다. 2026-07-06에 특정 CLI의 직접 호출을 제한하는 훅을 구성했고, JSON 입력과 명령 문자열을 조합한 15개 케이스가 예상과 일치했다고 기록돼 있다. 체인 명령과 절대경로 호출의 거부 판정도 포함됐으며, macOS 라이브 실행에서 대상 명령이 차단된 기록이 있다. 이는 해당 사용자 훅의 과거 검증 결과이지 Claude Code 내장 권한 전체의 검증 결과는 아니다.

그 훅은 fail-open으로 설계됐다. 빈 명령이나 JSON 파싱 실패처럼 판별하지 못하는 입력은 통과시키며, 목적은 협업 규칙을 우회하는 직접 호출을 제한하는 것이었다. 따라서 차단 성공 사례를 ‘판별 실패 시에도 닫히는 안전 게이트’의 실증으로 사용할 수는 없다.

확인질문은 누구에게 가는가

자동 실행을 구성할 때는 승인 요청에 답할 연결이 있는지부터 구분해야 한다. 공식 문서에 따르면 비대화형 실행에도 외부 permission host를 연결할 수 있다. 문서의 예시는 Agent SDK의 권한 콜백이나 --permission-prompt-tool로 지정한 MCP 도구이며, 이런 호스트가 있으면 실행이 답변을 기다릴 수 있다. 출처: 외부 승인 호스트와 비대화형 실행 — 조회일 2026-09-19.

공식 문서에 따르면 답할 사람이 없을 때 --permission-prompts none을 지정하면 호스트에 묻거나 기다리지 않는다. 규칙·권한 모드와 PermissionRequest 훅으로 해결되지 않은 승인 요청은 거부되고, 실행은 계속되며 Claude에는 재시도하지 말라는 안내가 전달된다. 호스트 없는 -p 실행에서는 이런 요청이 플래그 유무와 관계없이 거부되지만, 플래그는 재시도하지 말라는 안내도 추가한다. 출처: 무인 실행의 승인 요청 처리 — 조회일 2026-09-19.

공식 문서에 따르면 --output-format stream-json에서는 거부가 permission_denied 시스템 메시지로 나타나고, 최종 결과의 permission_denials에도 나열된다. 이는 거부 기록이며 모든 승인을 기록하는 내장 감사 로그로 해석해서는 안 된다. 변경 사항을 감사 로그에 덧붙이는 훅 예시는 별도로 제공되며, 그런 기록은 운영자가 직접 구성하는 기능이다. 출처: 권한 거부 출력, 감사 로그를 만드는 훅 예시 — 조회일 2026-09-19.

허용됐어도 어디까지 손댈 수 있는지는 다른 문제다

명령의 허용 범위를 정했다면 실행 환경의 접근 범위도 살펴야 한다. 공식 문서에 따르면 샌드박스는 파일 시스템과 네트워크의 접근 경계를 정하고 운영체제가 이를 명령과 자식 프로세스에 강제하는 방식이다. 파일 시스템 격리는 읽기·쓰기 경로를, 네트워크 격리는 연결할 도메인을 제한한다. 출처: 샌드박스의 접근 경계 — 조회일 2026-09-19.

공식 문서에 따르면 auto-allow에서는 샌드박스 안에서 실행할 수 있는 명령을 별도 확인 없이 자동 승인한다. 샌드박스로 실행할 수 없는 명령은 일반 권한 흐름으로 돌아가며, 명시적 deny 규칙은 계속 존중된다. 따라서 모든 명령이 먼저 개별 승인을 받은 뒤 별도의 격리 검사를 다시 거친다는 고정 순서로 설명할 수는 없다. 출처: 샌드박스 auto-allow 동작 — 조회일 2026-09-19.

공식 문서에 따르면 파일 시스템 격리와 네트워크 격리는 각각 설정할 수 있다. 파일 시스템 격리를 끄면 호스트 파일 시스템의 읽기·쓰기 제한은 사라지지만, 네트워크 연결은 허용 도메인으로 계속 제한될 수 있다. 그러므로 ‘샌드박스가 켜져 있다’는 표시만으로 파일 접근까지 제한된다고 판단하지 말고 실제 설정 범위를 확인하는 편이 좋다. 출처: 파일 시스템 격리와 네트워크 격리 — 조회일 2026-09-19.

권한 게이트를 설계할 때 점검할 것

아래 표는 앞의 공식 문서 내용을 설정 점검 질문으로 바꾼 것이다. 각 행은 독자가 확인할 항목이며, 제품 내부 모듈이나 고정된 실행 순서를 나타내지 않는다. 특히 사용자 훅의 차단 정책과 내장 권한 규칙, 샌드박스의 자동 승인 조건을 구분해서 읽어야 한다.

점검 표의 일부를 2행 3열로 나타낸 그림이다. 열은 검사 층, 답하는 질문, 놓치기 쉬운 지점이다. 첫 행의 규칙 기반 1차 판정은 어떤 도구와 패턴을 허용하거나 막는지 묻고, 규칙이 실행 중 갱신되어 같은 턴의 다음 도구 호출부터 적용된다는 점을 놓치기 쉽다. 둘째 행의 명령 내용 2차 검사는 허용 패턴에 실제 명령 전체가 맞는지 묻고, 옵션과 복합 명령의 각 하위 명령을 빠뜨리기 쉽다.
권한 게이트는 층마다 확인할 질문과 놓치기 쉬운 지점이 달라 설정을 따로 점검해야 한다는 뜻이다.
검사 층 답하는 질문 놓치기 쉬운 지점
규칙 기반 1차 판정 어떤 도구·패턴을 허용하거나 막는가 규칙이 실행 중 갱신되는 상태라는 점: 공식 문서에 따르면 변경은 같은 턴의 다음 도구 호출부터 적용된다. 권한 문서 — 조회일 2026-09-19.
명령 내용 2차 검사 허용 패턴에 실제 명령 전체가 맞는가 옵션·인자와 복합 명령의 각 하위 명령을 빠뜨리는 경우
경로 검증 링크와 실제 대상이 허용 범위 안인가 allow는 두 경로 모두, deny는 어느 한 경로의 일치로 적용된다는 차이
승인 요청 연결 외부 승인 호스트가 있는가, 답변을 기다릴 수 있는가 호스트 없는 실행의 호출 거부를 전체 실행 중단으로 오해하는 경우
실행 격리 명령이 접근할 파일과 도메인은 어디까지인가 auto-allow와 개별 승인, 파일 시스템 격리와 네트워크 격리의 차이
기록 거부 출력과 직접 구성한 감사 기록을 구분하는가 내장 거부 목록을 모든 승인에 대한 감사 로그로 해석하는 경우

셸 명령을 맡기기 전에는 다음 항목부터 확인할 수 있다.

  • 도구 전체 허용과 명령 패턴 허용의 범위를 구분했는가.
  • 저장된 규칙의 출처와 수명, 작업 중 변경의 적용 시점을 확인했는가.
  • 비대화형 실행에 필요한 도구를 미리 승인하고, 외부 승인 호스트의 유무를 확인했는가.
  • 심볼릭 링크의 실제 대상까지 포함해 경로 규칙을 읽었는가.
  • 사용자 훅이 판별 실패 시 통과시키는지 차단하는지 확인했는가.
  • 샌드박스의 파일 시스템·네트워크 범위와 거부 기록을 확인할 방법을 정했는가.

필요한 작업 범위를 먼저 정하면 권한 설정에서 확인할 대상도 구체적이 된다. 작업 자체의 범위를 정하는 질문은 AI 에이전트에게 일을 맡기기 전에 계약을 정하는 법에서 이어 볼 수 있다. 여기서는 그 범위에 맞춰 허용 패턴, 승인 요청의 처리 방식, 실행 환경의 접근 범위를 각각 점검하는 데 집중하면 된다.

자주 묻는 질문

허용 목록에 있는 도구라면 어떤 옵션을 붙여도 안전한가?

아니다. Claude Code의 Bash 규칙은 정확한 명령이나 와일드카드 패턴으로 범위를 좁힐 수 있고, 복합 명령은 하위 명령별로 판정한다. 도구 이름 전체를 허용하는 규칙은 옵션과 인자까지 넓게 열 수 있으므로 실제 실행 범위에 맞는 구체적인 패턴을 써야 한다.

공식 문서에 따르면 위의 명령 패턴과 하위 명령 판정이 적용된다. 출처: Bash 권한 규칙 — 조회일 2026-09-19.

비대화형 실행에서 확인질문이 나오면 승인을 기다리면 되는가?

외부 승인 호스트의 유무에 따라 다르다. 호스트 없는 claude -p 실행에서 규칙·훅·권한 모드로도 승인이 해결되지 않으면 해당 도구 호출은 거부되고 실행은 계속된다. 호스트가 연결돼 있으면 답변을 기다릴 수 있다. --allowedTools, allow 규칙, 권한 모드로 필요한 범위를 미리 승인하되 작업에 필요하지 않은 도구까지 넓게 열지 않아야 한다.

공식 문서에 따르면 호스트를 기다리지 않게 하려면 --permission-prompts none을 지정할 수 있다. 출처: 비대화형 승인 요청 처리 — 조회일 2026-09-19.

허용된 폴더 안의 경로라면 심볼릭 링크도 안전한가?

아니다. Claude Code의 allow 규칙은 링크 경로와 실제 대상이 모두 일치해야 통과하고, deny 규칙은 둘 중 하나만 일치해도 차단한다. 허용 폴더 안의 링크가 범위 밖을 가리키면 자동 허용되지 않는다.

공식 문서에 따르면 링크와 대상에 위의 비대칭 규칙이 적용된다. 출처: 심볼릭 링크 권한 처리 — 조회일 2026-09-19.

명령 실행이 허용되면 파일 시스템 전체에 접근하게 해도 되는가?

작업에 필요한 파일과 네트워크 접근 범위를 별도로 정하는 편이 좋다. 샌드박스의 파일 시스템 격리와 네트워크 격리는 서로 다른 설정이다. auto-allow에서는 샌드박스로 실행 가능한 명령이 개별 확인 없이 자동 승인되므로, 허용 여부와 함께 실제 격리 설정을 확인해야 한다.

공식 문서에 따르면 auto-allow의 자동 승인 조건과 두 격리 범위는 구분된다. 출처: 샌드박스 설정 — 조회일 2026-09-19.