תיעוד 144

הגדרת הרשאות

שלוט באופן שבו הסוכן שלך משתמש בכלים בעזרת מצבי הרשאה, hooks, וכללי allow/deny הצהרתיים.

ה-SDK של Claude Agent מספק בקרות הרשאה לניהול האופן שבו Claude משתמש בכלים. השתמש במצבי הרשאה ובכללים כדי להגדיר מה מורשה אוטומטית, וב-callback של canUseTool כדי לטפל בכל השאר בזמן ריצה.

#כיצד נבדקות הרשאות

כאשר Claude מבקש כלי, ה-SDK בודק הרשאות בסדר הבא:

Hooks: הרץ hooks תחילה. hook יכול לדחות את הקריאה מיד או להעביר אותה הלאה. hook שמחזיר allow אינו מדלג על כללי ה-deny וה-ask שבהמשך: אלה נבדקים ללא קשר לתוצאת ה-hook. אישור של hook מסוג PreToolUse גם אינו יכול לאשר מחיקה של rm או rmdir המכוונת אל נתיב קריטי.
כללי deny: בדוק כללי deny (מתוך disallowed_tools ומתוך settings.json). אם כלל deny מתאים, הכלי נחסם, אפילו במצב bypassPermissions. כללי deny בעלי שם בלבד (bare-name) כמו Bash מסירים את הכלי מההקשר של Claude עוד לפני שהבדיקה הזו מתחילה, ולכן רק כללים בעלי טווח מוגדר כמו Bash(rm *) נבדקים בשלב זה.
כללי ask: בדוק כללי ask מתוך settings.json. אם כלל ask מתאים, הקריאה מועברת הלאה אל ה-callback של canUseTool לקבלת אישור, אפילו במצב bypassPermissions.

כלים הדורשים אינטראקציה עם המשתמש מתנהגים באותו אופן: AskUserQuestion וכלי MCP שהשרת שלהם מגדיר _meta["anthropic/requiresUserInteraction"] תמיד מועברים אל ה-callback, אפילו כאשר כלל allow מתאים. במצב dontAsk שני המקרים נדחים במקום זאת, מכיוון שמצב זה אינו מציג שאלות לעולם. ההערה (annotation) של MCP דורשת את Claude Code גרסה v2.1.199 ומעלה.

כלי claude.ai connector שהארגון שלך הגדיר כ-ask עוזבים אף הם את הזרימה בשלב זה. כל קריאה מועברת אל ה-callback, אפילו במצב bypassPermissions ואפילו כאשר כלל allow מתאים. ה-callback מקבל את הסיבה Your organization requires approval for this tool. במצב dontAsk הקריאה נדחית במקום זאת, מכיוון שמצב זה אינו מציג שאלות לעולם.

מצב הרשאה: החל את מצב ההרשאה הפעיל. המצב bypassPermissions מאשר כל דבר שמגיע לשלב זה, למעט מחיקות של rm ו-rmdir המכוונות אל נתיב קריטי, אשר מועברות הלאה במקום זאת. המצב acceptEdits מאשר את פעולות הקבצים המפורטות תחת מצב קבלת עריכות. המצב plan מנתב כלי עריכת קבצים וכלי כתיבה של המעטפת (shell) אל ה-callback של canUseTool ללא קשר לכללי allow, כך שפעולות כתיבה אינן יכולות לקבל אישור אוטומטי בזמן תכנון. מצבים אחרים מועברים הלאה.
כללי allow: בדוק כללי allow (מתוך allowed_tools ומתוך settings.json). אם כלל מתאים, הכלי מאושר. מחיקות של rm ו-rmdir המכוונות אל נתיב קריטי לעולם אינן מאושרות על ידי כלל allow: הן מגיעות ל-callback שלך במצבים המציגים שאלות, עוברות אל ה-classifier במצב auto ב-Claude Code גרסה v2.1.218 ומעלה, ונדחות במצב dontAsk.
ה-callback של canUseTool: אם הקריאה לא הוכרעה באף אחד מהשלבים לעיל, קרא ל-callback של canUseTool לקבלת החלטה. במצב dontAsk, שלב זה מדולג והכלי נדחה.

ב-TypeScript SDK, אם תגדיר permissionPrompts: 'none', ה-callback שלך לא ייקרא בשלב זה. ל-hook מסוג PermissionRequest עדיין יש הזדמנות להחליט, ואם הוא אינו מחליט, Claude Code דוחה את הקריאה. אפשרות זו דורשת את Claude Code גרסה v2.1.259 ומעלה.

תרשים זרימת בדיקת ההרשאות

אם תעביר callback של canUseTool בתצורה שבה ה-TypeScript SDK מצפה שסדר הבדיקה יאשר קריאות באופן אוטומטי לפני הפנייה אל ה-callback, ה-SDK מפיק אזהרת תהליך של Node.js פעם אחת בעת בניית השאילתה. קוד האזהרה הוא CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. שתי תצורות גורמות להפקתה:

permissionMode: 'bypassPermissions', אשר מאשר אוטומטית כל קריאה שמגיעה לשלב מצב ההרשאה, מלבד פעולות שאף מצב אינו מאשר אוטומטית.
כל ערך שם בלבד (bare entry) ב-allowedTools כגון "Read", אשר מאשר אוטומטית את הכלי כולו לפני הפנייה אל ה-callback, מלבד פעולות שאף מצב אינו מאשר אוטומטית.

ערכים עם מפרט (specifier) כגון Bash(ls *) ומצב acceptEdits אינם גורמים לאזהרה, וכללי allow המגיעים מקובצי הגדרות (settings) אינם גלויים לבדיקה זו.

האזן באמצעות process.on('warning', ...) והתאם את הקוד כדי לתעד אותו ביומן או להשתיק אותו. כדי לסנן כל קריאת כלי ללא קשר למצב ולכללים, השתמש ב-hook מסוג PreToolUse במקום זאת.

דף זה מתמקד בכללי allow ו-deny ובמצבי הרשאה. עבור השלבים האחרים:

Hooks: הרצת קוד מותאם אישית כדי לאשר, לדחות או לשנות בקשות לכלים. ראה שליטה בביצוע באמצעות hooks.
ה-callback של canUseTool: הצגת שאלות לאישור המשתמש בזמן ריצה, כאשר אף שלב מוקדם יותר אינו מכריע את הקריאה. ראה טיפול באישורים ובקלט משתמש.

#כללי allow ו-deny

allowed_tools ו-disallowed_tools (ב-TypeScript: allowedTools / disallowedTools) מוסיפים ערכים לרשימות כללי ה-allow וה-deny בזרימת הבדיקה שלעיל. אם תציין את אחד מכלי מעקב המשימות ב-allowed_tools, Claude Code גם מצרף את ההפעלה לכך. כל כלי אחר שאינו מופיע ב-allowed_tools עדיין זמין עבור Claude ומועבר הלאה אל מצב ההרשאה. כללי deny מתנהגים באופן שונה בהתאם לשאלה אם הם מציינים שם של כלי או מגדירים תבנית טווח בתוכו.

אפשרות	השפעה
`allowed_tools=["Read", "Grep"]`	`Read` ו-`Grep` מאושרים אוטומטית. כלים אחרים שאינם רשומים כאן עדיין קיימים ומועברים הלאה אל מצב ההרשאה ואל `canUseTool`.
`disallowed_tools=["Bash"]`	הגדרת הכלי `Bash` מוסרת מהבקשה. Claude אינו רואה את הכלי ואינו יכול לנסות להשתמש בו.
`disallowed_tools=["Bash(rm *)"]`	`Bash` נשאר זמין. קריאות התואמות ל-`rm *` נדחות בכל מצב הרשאה, כולל `bypassPermissions`. קריאות `Bash` אחרות מועברות הלאה אל מצב ההרשאה.
`disallowed_tools=["*"]`	כל הגדרות הכלים מוסרות מהבקשה. תבניות glob של שמות כלים נתמכות בכללי `deny`: `""` מתאים לכל כלי, ו-`"mcp__"` מתאים לכל כלי MCP בכל השרתים.

כללי allow מקבלים תבניות glob של שמות כלים רק לאחר קידומת מילולית של mcp__<server>__. חלק השרת חייב להיות ללא תבנית glob, כך שהכלל יציין שרת ספציפי שהגדרת: mcp__puppeteer__* מתאים לכל כלי משרת ה-puppeteer, ו-mcp__github__get_* מתאים לכלי ה-get_ שלו. ערך שאינו מעוגן כגון allowed_tools=["*"] או allowed_tools=["mcp__*"] זוכה להתעלמות עם אזהרה בעת ההפעלה ואינו מאשר שום דבר באופן אוטומטי.

כללים בעלי טווח מוגדר עבור Read ו-Edit מקבלים תבנית נתיב. כללי Edit(path) חלים על כל הכלים המובנים שכותבים קבצים, כולל Write ו-NotebookEdit: כלל Write(path) לעולם אינו מותאם על ידי בדיקות הרשאות הקבצים.

השתמש ב-//path עבור נתיב קבצים מוחלט: כלל deny של Edit(//secrets/**) חוסם כתיבות בכל מקום תחת /secrets בדיסק. עם לוכסן מוביל יחיד, Edit(/secrets/**) מתעגן במקור של הכלל במקום זאת. עבור כללים המועברים דרך allowed_tools או disallowed_tools, המשמעות היא ספריית העבודה של ההפעלה, ולכן הכלל אינו חוסם את /secrets בדיסק. ראה כללי Read ו-Edit עבור ארבע צורות העיגון וכיצד כללים מקובצי הגדרות נפתרים.

[!WARNING] כלים המאושרים אוטומטית לעולם אינם מגיעים אל canUseTool. קריאת כלי שאושרה בכל שלב מוקדם יותר, על ידי acceptEdits או bypassPermissions, או על ידי כלל allow, מדלגת על ה-callback שלך של canUseTool, ולכן בדיקות הרשאה שמוגדרות שם נעקפות בשקט עבור אותו כלי. AskUserQuestion, כלי MCP המסומנים כ-_meta["anthropic/requiresUserInteraction"], כלי מחברים שהארגון שלך הגדיר כ-ask, ומחיקות של rm ו-rmdir המכוונות אל נתיב קריטי עדיין מגיעים ל-callback, אפילו כאשר כלל allow מתאים. במצב auto, מחיקות של נתיב קריטי מועברות אל ה-classifier במקום ל-callback, בעוד ששאר הקריאות המפורטות כאן עדיין מגיעות אליו: ניתוב ה-classifier דורש את Claude Code גרסה v2.1.218 ומעלה. במצב dontAsk קריאות אלה נדחות במקום זאת, ללא הפעלת ה-callback.

הכיסוי תלוי במבנה הערך: שם בלבד כמו Read או mcp__github__get_issue מאשר אוטומטית כל קריאה לאותו כלי מלבד החריגים שלעיל, בעוד שכלל בעל טווח מוגדר כמו Bash(ls *) מאשר אוטומטית רק קריאות תואמות וקריאות Bash אחרות עדיין מועברות אל ה-callback. עבור בדיקות שחייבות לרוץ בכל קריאת כלי, השתמש ב-hook מסוג PreToolUse: ה-hooks רצים לפני כל שלב אחר, ודחייה של hook חלה אפילו במצב bypassPermissions.

עבור סוכן נעול ומאובטח, שלב את allowedTools עם permissionMode: "dontAsk". הכלים המפורטים מאושרים, מלבד הכלים שתמיד מציגים שאלות המצוינים באזהרה לעיל: כל דבר אחר נדחה ישירות במקום להציג שאלה:

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

[!WARNING] allowed_tools אינו מגביל את bypassPermissions. allowed_tools מאשר מראש את הכלים שאתה מפרט. כלים אחרים שאינם ברשימה אינם מותאמים על ידי אף כלל allow ומועברים הלאה אל מצב ההרשאה, שבו bypassPermissions מאשר אותם. הגדרת allowed_tools=["Read"] לצד permission_mode="bypassPermissions" עדיין מאשרת כל כלי, כולל Bash, Write, ו-Edit. אם אתה זקוק ל-bypassPermissions אך רוצה לחסום כלים ספציפיים, השתמש ב-disallowed_tools.

באפשרותך גם להגדיר כללי allow, deny, ו-ask באופן הצהרתי בתוך .claude/settings.json. כללים אלה נקראים כאשר מקור ההגדרות project מופעל, כפי שמוגדר כברירת מחדל באפשרויות של query(). אם תגדיר את setting_sources (ב-TypeScript: settingSources) במפורש, כלול את "project" כדי שהם יחולו. ראה הגדרות הרשאה עבור תחביר הכללים.

#מצבי הרשאה

מצבי הרשאה מספקים שליטה גלובלית על האופן שבו Claude משתמש בכלים. ניתן להגדיר את מצב ההרשאה בעת קריאה ל-query() או לשנות אותו באופן דינמי במהלך הפעלות בהזרמה (streaming).

#מצבים זמינים

ה-SDK תומך במצבי ההרשאה הבאים:

מצב	תיאור	התנהגות כלים
`default`	התנהגות הרשאות רגילה	אין אישורים אוטומטיים: כלים ללא התאמה מפעילים את ה-callback שלך של `canUseTool`
`dontAsk`	דחייה במקום הצגת שאלה	כל דבר שלא אושר מראש על ידי `allowed_tools` או כללים נדחה: כלי מחברים שהארגון שלך הגדיר כ-`ask` וכלים הדורשים אינטראקציה עם המשתמש נדחים אפילו אם אישרת אותם מראש, וכך גם מחיקות של `rm` ו-`rmdir` המכוונות אל נתיב קריטי. ה-callback של `canUseTool` אינו נקרא לעולם
`acceptEdits`	קבלה אוטומטית של עריכות קבצים	עריכות קבצים ופעולות מערכת קבצים (`mkdir`, `rm`, `mv`, וכו') מאושרות באופן אוטומטי
`bypassPermissions`	עקיפת בדיקות הרשאה	כלים רצים ללא שאלות הרשאה, למעט פעולות שאף מצב אינו מאשר אוטומטית. השתמש בזהירות
`plan`	מצב תכנון	Claude חוקר ומתכנן מבלי לערוך את קובצי המקור שלך: עריכות קבצים אינן מאושרות אוטומטית לעולם ומציגות שאלה דרך ה-callback של `canUseTool`
`auto`	אישורים בסיווג מודל	מסווג מודל (classifier) מאשר או דוחה שאלות הרשאה. ראה מצב Auto למידע על זמינות

[!WARNING] הורשה של תת-סוכנים: תת-סוכנים יורשים את מצב ההרשאה של הפעלת ההורה. הערך permissionMode של AgentDefinition יכול לדרוס אותו, למעט כאשר ההורה משתמש ב-bypassPermissions, acceptEdits, או auto: מצבים אלה חלים על כל תת-סוכן ואינם ניתנים לדריסה עבור תת-סוכן בודד. בנוסף, Claude Code מתעלם מ-permissionMode: "bypassPermissions" של הגדרה כאשר מצב עקיפה מושבת על ידי permissions.disableBypassPermissionsMode, כך שאותו תת-סוכן רץ עם המצב של הפעלת ההורה.

לתת-סוכנים עשויות להיות הנחיות מערכת (system prompts) שונות והתנהגות פחות מוגבלת מזו של הסוכן הראשי שלך, ולכן הורשת bypassPermissions מעניקה להם גישה מלאה ואוטונומית למערכת. הפעולות שאף מצב אינו מאשר אוטומטית עדיין חלות.

#הגדרת מצב הרשאה

ניתן להגדיר את מצב ההרשאה פעם אחת בעת התחלת שאילתה, או לשנות אותו באופן דינמי בזמן שההפעלה פעילה.

#בעת ביצוע שאילתה

העבר את permission_mode (ב-Python) או את permissionMode (ב-TypeScript) בעת יצירת שאילתה. מצב זה חל על כל ההפעלה אלא אם שונה באופן דינמי.

Python:

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())

TypeScript:

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" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

#במהלך הזרמה

קרא ל-set_permission_mode() (ב-Python) או ל-setPermissionMode() (ב-TypeScript) כדי לשנות את המצב באמצע ההפעלה. המצב החדש נכנס לתוקף מיד עבור כל בקשות הכלים הבאות. הדבר מאפשר לך להתחיל באופן מגביל ולהרחיב הרשאות ככל שנבנה אמון, למשל מעבר ל-acceptEdits לאחר בדיקת הגישה הראשונית של Claude.

Python:

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


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

        
# Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        
# Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

TypeScript:

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

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

#פירוט המצבים

#מצב קבלת עריכות (`acceptEdits`)

מאשר אוטומטית פעולות קבצים כך ש-Claude יכול לערוך קוד מבלי לשאול. כלים אחרים (כמו פקודות Bash שאינן פעולות במערכת הקבצים) עדיין דורשים הרשאות רגילות.

פעולות המאושרות אוטומטית:

עריכות קבצים (כלי Edit, Write)
פקודות מערכת קבצים: mkdir, touch, rm, rmdir, mv, cp, sed

שתיהן חלות רק על נתיבים בתוך ספריית העבודה או additionalDirectories. נתיבים מחוץ לטווח זה, כתיבה לנתיבים מוגנים, ומחיקות של rm ו-rmdir המכוונות אל נתיב קריטי עדיין מציגות שאלות לאישור.

השתמש כאשר: אתה סומך על העריכות של Claude ורוצה איטרציה מהירה יותר, למשל במהלך בניית אב-טיפוס או בעבודה בספרייה מבודדת.

#מצב אל תשאל (`dontAsk`)

ממיר כל שאלת הרשאה לדחייה. כלים שאושרו מראש על ידי allowed_tools, כללי allow בתוך settings.json, או hook פועלים כרגיל. כלי מחברים שהארגון שלך הגדיר כ-ask, כלים הדורשים אינטראקציה עם המשתמש, ומחיקות של rm ו-rmdir המכוונות אל נתיב קריטי נדחים אפילו כאשר כלל allow מתאים. אישור של hook מסוג PreToolUse גם אינו מאשר מחיקת נתיב קריטי. כל השאר נדחה מבלי לקרוא ל-canUseTool.

השתמש כאשר: אתה רוצה משטח כלים קבוע ומפורש עבור סוכן הפועל ברקע ללא ממשק (headless) ומעדיף דחייה מוחלטת על פני הסתמכות שקטה על כך ש-canUseTool אינו קיים.

#מצב עקיפת הרשאות (`bypassPermissions`)

מאשר אוטומטית שימושים בכלים מבלי לשאול, למעט המקרים המפורטים באזהרה שלהלן. hooks עדיין רצים ויכולים לחסום פעולות לפי הצורך.

[!WARNING] השתמש בזהירות מרבית. ל-Claude יש גישה מלאה למערכת במצב זה. השתמש רק בסביבות מבוקרות שבהן אתה בוטח בכל הפעולות האפשריות.

allowed_tools אינו מגביל מצב זה. כל כלי מאושר, לא רק אלה שציינת. בקרות אלה עדיין חלות:

כללי deny, כללי ask מפורשים, ו-hooks נבדקים לפני בדיקת המצב ועדיין יכולים לחסום כלי.

כלי מחברים שהארגון שלך הגדיר כ-ask, כלים הדורשים אינטראקציה עם המשתמש, ומחיקות של rm ו-rmdir המכוונות אל נתיב קריטי עדיין מועברים אל ה-callback שלך של canUseTool.

ההגנות על העברת הודעות בין הפעלות עדיין חלות.

#מצב תכנון (`plan`)

Claude חוקר את בסיס הקוד ומפיק תוכנית מבלי לערוך את קובצי המקור שלך. כלים לקריאה בלבד רצים כפי שהם רצים במצב הרשאה default.

עריכות קבצים אינן מאושרות אוטומטית לעולם במצב תכנון, אפילו כאשר כלל allow מתאים. במקום זאת, הן מציגות שאלות דרך ה-callback שלך של canUseTool. ב-Claude Code גרסה v2.1.212 ומעלה, פקודות מעטפת המשנות קבצים, כגון touch ו-rm, מגיעות אל ה-callback שלך של canUseTool באותו אופן.

Claude עשוי להשתמש ב-AskUserQuestion כדי להבהיר דרישות לפני סיום התוכנית. ראה טיפול באישורים ובקלט משתמש לטיפול בשאלות אלו.

השתמש כאשר: אתה רוצה ש-Claude יציע שינויים מבלי לבצע אותם, למשל במהלך סקירת קוד או כאשר אתה צריך לאשר שינויים לפני ביצועם.

#משאבים קשורים

עבור השלבים האחרים בזרימת בדיקת ההרשאות:

טיפול באישורים ובקלט משתמש: שאלות אישור אינטראקטיביות ושאלות הבהרה
מדריך Hooks: הרצת קוד מותאם אישית בנקודות מפתח במחזור החיים של הסוכן
כללי הרשאה: כללי allow/deny הצהרתיים בתוך settings.json