Configure permissions

기준일: 2026-07-26
공식 기준: Configure permissions

Configure permissions 문서는 Claude Code 공식 문서(agent-sdk/permissions)를 한국어로 정리한 가이드입니다. Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules.

한국어 가이드 범위: agent-sdk/permissions 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Configure permissions
• How permissions are evaluated
• Allow and deny rules
• Permission modes
• Available modes
• Set permission mode
• Mode details
• Related resources

상세 내용

Configure permissions

Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

How permissions are evaluated

When Claude requests a tool, the SDK checks permissions in this order:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• permissionMode: 'bypassPermissions', which auto-approves every call that reaches the permission mode step
• Each bare allowedTools entry such as "Read", which auto-approves that whole tool before the callback is consulted
• Hooks: run custom code to allow, deny, or modify tool requests. See Control execution with hooks.
• canUseTool callback: prompt users for approval at runtime, when no earlier step resolves the call. See Handle approvals and user input.

Allow and deny rules

allowed_tools and disallowed_tools (TypeScript: allowedTools / disallowedTools) add entries to the allow and deny rule lists in the evaluation flow above. Allow rules only affect approval: a tool not listed in allowed_tools is still available to Claude and falls through to the permission mode. Deny rules behave differently depending on whether they name a tool or scope a pattern within one.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Option	Effect
allowed_tools=["Read", "Grep"]	Read and Grep are auto-approved. Tools not listed here still exist and fall through to the permission mode and canUseTool.
disallowed_tools=["Bash"]	The Bash tool definition is removed from the request. Claude does not see the tool and cannot attempt it.
disallowed_tools=["Bash(rm *)"]	Bash stays available. Calls matching rm * are denied in every permission mode, including bypassPermissions. Other Bash calls fall through to the permission mode.
disallowed_tools=["*"]	Every tool definition is removed from the request. Tool-name globs are supported in deny rules: "*" matches every tool and "mcp__*" matches every MCP tool across all servers.

Permission modes

Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling query() or change it dynamically during streaming sessions.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Available modes

Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting bypassPermissions grants them full, autonomous system access. Explicit ask rules, connector tools your organization set to ask, and tools that require user interaction still force a prompt.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Mode	Description	Tool behavior
default	Standard permission behavior	No auto-approvals; unmatched tools trigger your canUseTool callback
dontAsk	Deny instead of prompting	Anything not pre-approved by allowed_tools or rules is denied; connector tools your organization set to ask and tools that require user interaction are denied even if you've pre-approved them. canUseTool is never called
acceptEdits	Auto-accept file edits	File edits and filesystem operations (mkdir, rm, mv, etc.) are automatically approved
bypassPermissions	Bypass permission checks	Tools run without permission prompts, except tools matched by an explicit ask rule, connector tools your organization set to ask, and tools that require user interaction (use with caution)
plan	Planning mode	Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your canUseTool callback
auto	Model-classified approvals	A model classifier approves or denies permission prompts. See Auto mode for availability

Set permission mode

You can set the permission mode once when starting a query, or change it dynamically while the session is active.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests. This lets you start restrictive and loosen permissions as trust builds, for example switching to `acceptEdits` after reviewing Claude's initial approach.

Mode details

Auto-approves file operations so Claude can edit code without prompting. Other tools (like Bash commands that aren't filesystem operations) still require normal permissions.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• File edits (Edit, Write tools)
• Filesystem commands: mkdir, touch, rm, rmdir, mv, cp, sed

Related resources

For the other steps in the permission evaluation flow:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Handle approvals and user input: interactive approval prompts and clarifying questions
• Hooks guide: run custom code at key points in the agent lifecycle
• Permission rules: declarative allow/deny rules in settings.json

실습 체크리스트

1. 공식 문서와 로컬/SDK 버전을 대조합니다.
2. 관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
3. Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
4. 권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

**`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` only pre-approves the tools you list. Unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`.

You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. These rules are read when the `project` setting source is enabled, which it is for default `query()` options. If you set `setting_sources` (TypeScript: `settingSources`) explicitly, include `"project"` for them to apply. See [Permission settings](/docs/en/settings#permission-settings) for the rule syntax.

## Permission modes

Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions.

### Available modes

The SDK supports these permission modes:

| Mode                | Description                  | Tool behavior                                                                                                                                                                                                                                                                          |
| :------------------ | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default`           | Standard permission behavior | No auto-approvals; unmatched tools trigger your `canUseTool` callback                                                                                                                                                                                                                  |
| `dontAsk`           | Deny instead of prompting    | Anything not pre-approved by `allowed_tools` or rules is denied; connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) and tools that require user interaction are denied even if you've pre-approved them. `canUseTool` is never called  |
| `acceptEdits`       | Auto-accept file edits       | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved                                                                                                                                                          |
| `bypassPermissions` | Bypass permission checks     | Tools run without permission prompts, except tools matched by an explicit [`ask` rule](#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction (use with caution) |
| `plan`              | Planning mode                | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback                                                                                                                                          |
| `auto`              | Model-classified approvals   | A model classifier approves or denies permission prompts. See [Auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) for availability                                                                                                                                      |

  **Subagent inheritance:** Subagents inherit the parent session's permission mode. An [`AgentDefinition`'s `permissionMode`](/docs/en/agent-sdk/typescript#agentdefinition) can override it, except when the parent uses `bypassPermissions`, `acceptEdits`, or `auto`: those modes apply to every subagent and can't be overridden per subagent.

  Subagents may have different system prompts and less constrained behavior than your main agent, so inheriting `bypassPermissions` grants them full, autonomous system access. Explicit [`ask` rules](#how-permissions-are-evaluated), connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), and tools that require user interaction still force a prompt.

### Set permission mode

You can set the permission mode once when starting a query, or change it dynamically while the session is active.

  

    Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query. This mode applies for the entire session unless changed dynamically.

Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests. This lets you start restrictive and loosen permissions as trust builds, for example switching to `acceptEdits` after reviewing Claude's initial approach.

관련 링크

• 공식 원문: agent-sdk/permissions
• 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·API 이름은 설치 버전에 따라 달라질 수 있습니다.