SpyBara
Go Premium

agent-sdk/permissions.md 2026-09-13 21:00 UTC to 2026-09-14 22:58 UTC

This page contains 74 additions and 74 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Fri 25 23:58

권한 구성

권한 모드, 훅, 선언적 허용/거부 규칙을 사용하여 에이전트가 도구를 사용하는 방식을 제어합니다.

Claude Agent SDK는 Claude가 도구를 사용하는 방식을 관리하기 위한 권한 제어를 제공합니다. 권한 모드와 규칙을 사용하여 자동으로 허용되는 항목을 정의하고, canUseTool 콜백을 사용하여 런타임에 다른 모든 항목을 처리합니다.

권한이 평가되는 방식

Claude가 도구를 요청할 때 SDK는 다음 순서로 권한을 확인합니다.

1

Hooks

먼저 hooks를 실행합니다. Hook은 호출을 완전히 거부하거나 통과시킬 수 있습니다. allow를 반환하는 Hook은 아래의 거부 및 확인 규칙을 건너뛰지 않습니다. 이러한 규칙은 Hook 결과와 관계없이 평가됩니다. PreToolUse Hook allow는 중요 경로를 대상으로 하는 rm 또는 rmdir 제거를 승인할 수 없습니다.

2

거부 규칙

deny 규칙(disallowed_tools 및 settings.json에서)을 확인합니다. 거부 규칙이 일치하면 bypassPermissions 모드에서도 도구가 차단됩니다. Bash와 같은 단순 이름 거부 규칙은 이 평가가 시작되기 전에 Claude의 컨텍스트에서 도구를 제거하므로 Bash(rm *)과 같은 범위가 지정된 규칙만 이 단계에서 확인됩니다.

3

확인 규칙

settings.json에서 ask 규칙을 확인합니다. ask 규칙이 일치하면 bypassPermissions 모드에서도 호출이 확인을 위해 canUseTool 콜백으로 전달됩니다.

사용자 상호작용이 필요한 도구는 동일하게 작동합니다. AskUserQuestion 및 서버가 _meta["anthropic/requiresUserInteraction"]을 설정하는 MCP 도구는 allow 규칙이 일치할 때도 항상 콜백으로 전달됩니다. dontAsk 모드에서는 이 모드가 절대 프롬프트하지 않기 때문에 두 경우 모두 거부됩니다. MCP 주석에는 Claude Code v2.1.199 이상이 필요합니다.

조직이 ask로 설정한 claude.ai connector 도구도 이 단계에서 흐름을 떠납니다. 모든 호출은 bypassPermissions 모드에서도, allow 규칙이 일치할 때도 콜백으로 전달됩니다. 콜백은 Your organization requires approval for this tool 이유를 받습니다. dontAsk 모드에서는 이 모드가 절대 프롬프트하지 않기 때문에 호출이 거부됩니다.

4

권한 모드

활성 권한 모드를 적용합니다.

  • bypassPermissions 모드에서 Claude Code는 이 단계에 도달하는 모든 것을 승인합니다. 단, 중요 경로를 대상으로 하는 rm 및 rmdir 제거는 대신 전달됩니다.
  • acceptEdits 모드에서 Claude Code는 Accept edits mode에 나열된 파일 작업을 승인합니다.
  • plan 모드에서 Claude Code는 allow 규칙과 관계없이 파일 편집 및 셸 쓰기 도구를 canUseTool 콜백으로 보내므로 계획 중에 쓰기 작업을 자동 승인할 수 없습니다.
  • 다른 모드에서는 요청이 전달됩니다.
5

허용 규칙

allow 규칙(allowed_tools 및 settings.json에서)을 확인합니다. 규칙이 일치하면 도구가 승인됩니다. 도구가 자체적으로 승인하는 호출도 이 단계에서 규칙 없이 해결됩니다. 예를 들어 작업 디렉토리 내의 파일 읽기 또는 읽기 전용 Bash 명령입니다. rm 및 rmdir 제거는 중요 경로를 대상으로 하는 경우 allow 규칙으로 절대 승인되지 않습니다. 프롬프트하는 모드에서는 콜백에 도달하고, Claude Code v2.1.218 이상의 auto 모드에서는 분류기로 이동하며, dontAsk 모드에서는 거부됩니다.

6

canUseTool 콜백

위의 어느 것도 해결하지 못하면 결정을 위해 canUseTool 콜백을 호출합니다. dontAsk 모드에서는 이 단계를 건너뛰고 도구가 거부됩니다.

TypeScript SDK에서 permissionPrompts: 'none'을 설정하면 콜백이 이 단계에서 호출되지 않습니다. PermissionRequest hook은 여전히 결정할 기회를 얻으며, 그렇지 않으면 Claude Code가 호출을 거부합니다. 이 옵션에는 Claude Code v2.1.259 이상이 필요합니다.

위의 단계와 일치하는 6단계 권한 평가 흐름의 다이어그램: 도구 요청이 hooks, 거부 규칙, 확인 규칙, 권한 모드, 허용 규칙 및 canUseTool을 통과합니다. Hooks, 거부 규칙 및 canUseTool은 Blocked로 라우팅할 수 있습니다. 권한 모드 bypass, 허용 규칙 및 canUseTool은 Execute로 라우팅할 수 있습니다. 확인 규칙은 canUseTool로 라우팅합니다. 위의 단계와 일치하는 6단계 권한 평가 흐름의 다이어그램: 도구 요청이 hooks, 거부 규칙, 확인 규칙, 권한 모드, 허용 규칙 및 canUseTool을 통과합니다. Hooks, 거부 규칙 및 canUseTool은 Blocked로 라우팅할 수 있습니다. 권한 모드 bypass, 허용 규칙 및 canUseTool은 Execute로 라우팅할 수 있습니다. 확인 규칙은 canUseTool로 라우팅합니다.

TypeScript SDK가 평가 순서를 자동 승인하도록 예상하는 구성에서 canUseTool 콜백을 전달하면 쿼리가 구성될 때 SDK는 Node.js 프로세스 경고를 한 번 내보냅니다. 경고의 코드는 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED입니다. 두 가지 구성이 이를 트리거합니다.

Bash(ls *)와 같은 지정자가 있는 항목과 acceptEdits 모드는 이를 트리거하지 않으며, 설정 파일에서 오는 허용 규칙은 확인에 표시되지 않습니다.

process.on('warning', ...)으로 수신하고 코드를 일치시켜 로깅하거나 억제합니다. 모드와 규칙과 관계없이 모든 도구 호출을 제어하려면 대신 PreToolUse hook을 사용합니다.

이 페이지는 허용 및 거부 규칙 및 권한 모드에 중점을 둡니다. 다른 단계의 경우:

  • Hooks: 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. Hooks로 실행 제어를 참조하세요.
  • canUseTool 콜백: 이전 단계에서 호출을 해결하지 못할 때 런타임에 사용자에게 승인을 요청합니다. 승인 및 사용자 입력 처리를 참조하세요.

허용 및 거부 규칙

allowed_tools 및 disallowed_tools (TypeScript: allowedTools / disallowedTools)는 위의 평가 흐름에서 허용 및 거부 규칙 목록에 항목을 추가합니다. 작업 추적 도구 중 하나를 allowed_tools에 이름 지으면 Claude Code도 세션을 옵트인합니다. allowed_tools에 나열되지 않은 다른 도구는 여전히 Claude에서 사용 가능하며, 승인이 필요한 호출은 권한 모드로 넘어갑니다. 거부 규칙은 도구의 이름을 지정하는지 또는 도구 내의 패턴을 범위 지정하는지에 따라 다르게 작동합니다.

옵션 효과
allowed_tools=["Read", "Grep"] Read 및 Grep은 자동 승인됩니다. 여기에 나열되지 않은 다른 도구는 여전히 존재하며, 승인이 필요한 호출은 권한 모드 및 canUseTool로 넘어갑니다.
disallowed_tools=["Bash"] Bash 도구 정의가 요청에서 제거됩니다. Claude는 도구를 보지 못하며 시도할 수 없습니다.
disallowed_tools=["Bash(rm *)"] Bash는 사용 가능한 상태로 유지됩니다. rm * 작성된 대로 일치하는 호출은 bypassPermissions를 포함한 모든 권한 모드에서 거부됩니다. /bin/rm을 포함한 다른 Bash 호출은 권한 모드로 넘어갑니다.
disallowed_tools=["*"] 모든 도구 정의가 요청에서 제거됩니다. 도구 이름 글롭은 거부 규칙에서 지원됩니다: "*"는 모든 도구와 일치하고 "mcp__*"는 모든 서버의 모든 MCP 도구와 일치합니다.

허용 규칙은 리터럴 mcp__<server>__ 접두사 이후에만 도구 이름 글롭을 허용합니다. 서버 세그먼트는 글롭이 없어야 하므로 규칙이 구성한 특정 서버의 이름을 지정합니다: mcp__puppeteer__*는 puppeteer 서버의 모든 도구와 일치하고, mcp__github__get_*는 해당 get_ 도구와 일치합니다. allowed_tools=["*"] 또는 allowed_tools=["mcp__*"]와 같은 앵커되지 않은 항목은 시작 경고와 함께 무시되며 아무것도 자동 승인하지 않습니다.

Read 및 Edit에 대한 범위 지정 규칙은 경로 패턴을 사용합니다. Edit(path) 규칙은 Write 및 NotebookEdit을 포함하여 파일을 쓰는 모든 기본 제공 도구를 관리합니다. Write(path) 규칙은 파일 권한 검사에 의해 일치되지 않습니다.

절대 파일 시스템 경로에는 //path를 사용합니다: Edit(//secrets/**) 거부 규칙은 디스크의 /secrets 아래 어디든지 쓰기를 차단합니다. 단일 슬래시를 사용하면 Edit(/secrets/**)는 규칙의 소스에서 앵커됩니다. allowed_tools 또는 disallowed_tools를 통해 전달된 규칙의 경우, 이는 세션의 작업 디렉토리를 의미하므로 규칙은 디스크의 /secrets를 차단하지 않습니다. 네 가지 앵커 형식과 설정 파일의 규칙이 어떻게 해결되는지는 Read 및 Edit 규칙을 참조하십시오.

잠금된 에이전트의 경우 allowedTools를 permissionMode: "dontAsk"와 쌍으로 지정합니다:

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

나열된 도구는 모드가 자동 승인하지 않는 작업을 제외하고 승인되며, 프롬프트를 표시할 다른 모든 호출은 대신 거부됩니다. default 모드에서 승인이 필요 없는 호출은 나열 여부와 관계없이 실행됩니다. 예를 들어 읽기 전용 Bash 명령, 실행 전에 묻지 않는 Agent와 같은 도구, 작업 디렉토리 내의 파일 읽기 등입니다. 도구를 Claude의 범위에서 완전히 제거하려면 disallowedTools에 단순 이름을 추가합니다.

.claude/settings.json에서 허용, 거부 및 요청 규칙을 선언적으로 구성할 수도 있습니다. 이러한 규칙은 project 설정 소스가 활성화될 때 읽혀지며, 기본 query() 옵션에 대해 활성화됩니다. setting_sources (TypeScript: settingSources)를 명시적으로 설정하면 적용되도록 "project"를 포함합니다. 규칙 구문은 권한 설정을 참조하십시오.

권한 모드

권한 모드는 Claude가 도구를 사용하는 방식을 전역적으로 제어합니다. query()를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.

사용 가능한 모드

SDK는 다음 권한 모드를 지원합니다.

모드 설명 도구 동작
default 표준 권한 동작 모드 기반 자동 승인 없음. 승인이 필요하고 허용 규칙과 일치하지 않는 호출은 canUseTool 콜백을 트리거합니다
dontAsk 프롬프트 대신 거부 그렇지 않으면 프롬프트를 표시할 모든 호출이 거부됩니다. allowed_tools 또는 규칙으로 승인된 호출과 default 모드에서 승인이 필요 없는 호출은 실행되며, 조직에서 ask로 설정한 커넥터 도구와 사용자 상호작용이 필요한 도구, 그리고 중요 경로를 대상으로 하는 rm 및 rmdir 제거는 사전 승인했더라도 거부됩니다. canUseTool은 호출되지 않습니다
acceptEdits 파일 편집 자동 수락 파일 편집 및 파일시스템 작업(mkdir, rm, mv 등)이 자동으로 승인됩니다
bypassPermissions 권한 확인 무시 모드가 자동 승인하지 않는 작업을 제외하고 도구가 권한 프롬프트 없이 실행됩니다. 주의해서 사용하세요
plan 계획 모드 Claude는 소스 파일을 편집하지 않고 탐색 및 계획을 수행합니다. 파일 편집은 자동 승인되지 않으며 canUseTool 콜백을 통해 프롬프트됩니다
auto 모델 분류 승인 모델 분류기가 권한 프롬프트를 승인하거나 거부합니다. 가용성은 자동 모드를 참조하세요

권한 모드 설정

쿼리를 시작할 때 권한 모드를 한 번 설정하거나 세션이 활성화된 동안 동적으로 변경할 수 있습니다.

쿼리를 생성할 때 permission_mode(Python) 또는 permissionMode(TypeScript)를 전달합니다. 이 모드는 동적으로 변경되지 않는 한 전체 세션에 적용됩니다.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default",  # Set the mode here
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

모드 세부 정보

편집 수락 모드(`acceptEdits`)

파일 작업을 자동 승인하여 Claude가 프롬프트 없이 코드를 편집할 수 있도록 합니다. 다른 도구(예: 파일시스템 작업이 아닌 Bash 명령)는 여전히 일반 권한이 필요합니다.

자동 승인 작업:

  • 파일 편집(Edit, Write 도구)
  • 파일시스템 명령: mkdir, touch, rm, rmdir, mv, cp, sed

둘 다 작업 디렉토리 또는 additionalDirectories 내의 경로에만 적용됩니다. acceptEdits 모드에서 Claude Code는 Claude가 다음을 수행할 때 요청을 자동 승인하지 않습니다.

  • 해당 범위 외의 경로에서 작업
  • 보호된 경로에 쓰기
  • rm 또는 rmdir로 중요 경로 제거

사용 시기: Claude의 편집을 신뢰하고 더 빠른 반복을 원할 때(예: 프로토타이핑 중이거나 격리된 디렉토리에서 작업할 때).

묻지 않기 모드(`dontAsk`)

canUseTool을 호출하지 않고 모든 권한 프롬프트를 거부로 변환합니다. allowed_tools, settings.json 허용 규칙 또는 훅으로 사전 승인된 도구와 파일 읽기(작업 디렉토리 내) 및 Agent 호출과 같이 default 모드에서 승인이 필요 없는 호출은 정상적으로 실행됩니다. 조직에서 ask로 설정한 커넥터 도구, 사용자 상호작용이 필요한 도구, 그리고 중요 경로를 대상으로 하는 rm 및 rmdir 제거는 허용 규칙이 일치하더라도 거부됩니다. PreToolUse 훅 허용도 중요 경로 제거를 해제하지 않습니다.

사용 시기: 헤드리스 에이전트에 대해 고정된 명시적 도구 표면을 원하고 canUseTool이 없는 것에 대한 자동 의존보다 명확한 거부를 선호할 때.

권한 무시 모드(`bypassPermissions`)

아래 나열된 경우를 제외하고 프롬프트 없이 도구 사용을 자동 승인합니다. 훅은 여전히 실행되며 필요한 경우 작업을 차단할 수 있습니다.

계획 모드(`plan`)

Claude는 소스 파일을 편집하지 않고 코드베이스를 탐색하고 계획을 생성합니다. 읽기 전용 도구는 default 권한 모드에서와 같이 실행됩니다.

파일 편집은 허용 규칙이 일치하더라도 계획 모드에서 자동 승인되지 않습니다. 대신 canUseTool 콜백을 통해 프롬프트됩니다. Claude Code v2.1.212 이상에서는 touch 및 rm과 같이 파일을 수정하는 셸 명령도 동일한 방식으로 canUseTool 콜백에 도달합니다.

Claude는 계획을 최종화하기 전에 요구 사항을 명확히 하기 위해 AskUserQuestion을 사용할 수 있습니다. 이러한 프롬프트 처리에 대해서는 승인 및 사용자 입력 처리를 참조하세요.

사용 시기: Claude가 변경 사항을 실행하지 않고 제안하기를 원할 때(예: 코드 검토 중이거나 변경 사항이 적용되기 전에 승인해야 할 때).

권한 평가 흐름의 다른 단계들: