Configure Permissions

ควบคุมวิธีที่ agent ของคุณใช้ tools ด้วย permission modes, hooks, และ declarative allow/deny rules

Claude Agent SDK ให้การควบคุม permissions เพื่อจัดการวิธีที่ Claude ใช้ tools ใช้ permission modes และ rules เพื่อกำหนดสิ่งที่อนุญาตโดยอัตโนมัติ และ callback canUseTool เพื่อจัดการสิ่งอื่นๆ ในเวลา runtime

note

หน้านี้ครอบคลุม permission modes และ rules สำหรับการสร้าง interactive approval flows ที่ users อนุมัติหรือปฏิเสธ tool requests ในเวลา runtime ดู Handle approvals and user input

วิธีการประเมิน Permissions

เมื่อ Claude ขอใช้ tool SDK ตรวจสอบ permissions ตามลำดับนี้:

1. Hooks - รัน hooks ก่อน hook สามารถปฏิเสธ call หรือส่งต่อไป hook ที่ return allow ไม่ข้าม deny และ ask rules ด้านล่าง

2. Deny rules - ตรวจสอบ deny rules (จาก disallowed_tools และ settings.json) หาก deny rule match ให้ tool ถูกบล็อก แม้แต่ใน bypassPermissions mode

3. Ask rules - ตรวจสอบ ask rules จาก settings.json หาก ask rule match call จะผ่านไปยัง callback canUseTool แม้ใน bypassPermissions mode

4. Permission mode - ใช้ permission mode ที่ active

5. Allow rules - ตรวจสอบ allow rules (จาก allowed_tools และ settings.json) หาก rule match tool จะได้รับการอนุมัติ

6. canUseTool callback - หากไม่ได้รับการ resolve โดยสิ่งใดข้างต้น เรียก callback canUseTool ใน dontAsk mode ขั้นตอนนี้จะถูกข้ามและ tool ถูกปฏิเสธ

Allow และ Deny Rules

allowed_tools และ disallowed_tools (TypeScript: allowedTools / disallowedTools) เพิ่ม entries ไปยัง allow และ deny rule lists

Option	Effect
allowed_tools=["Read", "Grep"]	Read และ Grep ได้รับการอนุมัติอัตโนมัติ tools ที่ไม่ได้ระบุยังมีอยู่และผ่านไปยัง permission mode
disallowed_tools=["Bash"]	Tool definition Bash ถูกลบออกจาก request Claude ไม่เห็น tool และไม่สามารถพยายามใช้มันได้
disallowed_tools=["Bash(rm *)"]	Bash ยังใช้ได้ calls ที่ match rm * ถูกปฏิเสธใน permission mode ทุกประเภท รวมถึง bypassPermissions Bash calls อื่นๆ ผ่านไปยัง permission mode
disallowed_tools=["*"]	Tool definitions ทุกอันถูกลบออกจาก request

สำหรับ agent ที่ locked down ให้จับคู่ allowedTools กับ permissionMode: "dontAsk" tools ที่ระบุได้รับการอนุมัติ สิ่งอื่นๆ ถูกปฏิเสธโดยตรงแทนการ prompt:

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

warning

allowed_tools ไม่ constrain bypassPermissions allowed_tools เพียง pre-approve tools ที่คุณระบุ tools ที่ไม่ได้ระบุไม่ match กับ allow rule ใดและผ่านไปยัง permission mode ที่ bypassPermissions อนุมัติพวกมัน การตั้ง allowed_tools=["Read"] ร่วมกับ permission_mode="bypassPermissions" ยังอนุมัติทุก tool รวมถึง Bash, Write, และ Edit หากคุณต้องการ bypassPermissions แต่ต้องการบล็อก tools เฉพาะ ให้ใช้ disallowed_tools

Permission Modes

Permission modes ให้ global control เหนือวิธีที่ Claude ใช้ tools

Modes ที่ใช้ได้

Mode	คำอธิบาย	พฤติกรรม tool
default	Standard permission behavior	ไม่มี auto-approvals tools ที่ไม่ match trigger callback canUseTool ของคุณ
dontAsk	Deny แทนการ prompt	ทุกอย่างที่ไม่ได้ pre-approved ถูกปฏิเสธ canUseTool ไม่ถูกเรียก
acceptEdits	Auto-accept file edits	File edits และ filesystem operations ได้รับการอนุมัติอัตโนมัติ
bypassPermissions	Bypass permission checks	Tools รันโดยไม่มี permission prompts เว้นแต่ explicit ask rule match (ใช้ด้วยความระมัดระวัง)
plan	Planning mode	Claude ค้นหาและ plan โดยไม่แก้ไข source files file edits ไม่ได้รับการ auto-approve และ prompt ผ่าน callback canUseTool
auto (TypeScript only)	Model-classified approvals	Model classifier อนุมัติหรือปฏิเสธแต่ละ tool call

warning

Subagent inheritance: เมื่อ parent ใช้ bypassPermissions, acceptEdits, หรือ auto subagents ทั้งหมด inherit mode นั้นและไม่สามารถ override ต่อ subagent ได้ explicit ask rule ยังบังคับ prompt อยู่

ตั้งค่า Permission Mode

คุณสามารถตั้ง permission mode ครั้งเดียวเมื่อเริ่ม query หรือเปลี่ยนแบบ dynamic ระหว่าง session ที่ active

เมื่อ query time:

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",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default"
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

ระหว่าง streaming:

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",
        )
    ) as client:
        await client.query("Help me refactor this code")

        # เปลี่ยน mode แบบ dynamic ระหว่าง mid-session
        await client.set_permission_mode("acceptEdits")

        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

รายละเอียดของ Modes

Accept edits mode (acceptEdits)

Auto-approve file operations เพื่อให้ Claude แก้ไข code โดยไม่ต้อง prompt tools อื่นๆ (เช่น Bash commands ที่ไม่ใช่ filesystem operations) ยังต้องการ permissions ปกติ

Auto-approved operations:

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

ใช้เมื่อ: คุณ trust การแก้ไขของ Claude และต้องการ iteration ที่เร็วขึ้น

Don't ask mode (dontAsk)

แปลง permission prompt ใดก็ตามเป็นการปฏิเสธ tools ที่ pre-approved โดย allowed_tools, settings.json allow rules, หรือ hook รันตามปกติ ทุกอย่างอื่นถูกปฏิเสธโดยไม่เรียก canUseTool

ใช้เมื่อ: คุณต้องการ tool surface ที่คงที่และชัดเจนสำหรับ headless agent

Bypass permissions mode (bypassPermissions)

Auto-approve tool uses ทั้งหมดโดยไม่มี prompts Hooks ยังทำงานและสามารถบล็อก operations ได้หากต้องการ

warning

ใช้ด้วยความระมัดระวังสูงสุด Claude มี full system access ใน mode นี้ ใช้เฉพาะในสภาพแวดล้อมที่ควบคุมได้ที่คุณ trust การดำเนินการที่เป็นไปได้ทั้งหมด

Plan mode (plan)

Claude ค้นหา codebase และผลิต plan โดยไม่แก้ไข source files Read-only tools รันเหมือนใน default mode File edits ไม่ได้รับการ auto-approve ใน plan mode แม้เมื่อ allow rule match

ใช้เมื่อ: คุณต้องการให้ Claude เสนอการเปลี่ยนแปลงโดยไม่ execute พวกมัน

เอกสารที่เกี่ยวข้อง

สำหรับขั้นตอนอื่นๆ ใน permission evaluation flow:

• Handle approvals and user input: interactive approval prompts และ clarifying questions
• Hooks guide: รัน custom code ณ จุดสำคัญใน agent lifecycle
• Permission rules: declarative allow/deny rules ใน settings.json