canUseTool callback 來在執行時處理其他所有情況。
權限如何被評估
當 Claude 請求一個工具時,SDK 按照以下順序檢查權限:1
Hooks
首先執行 hooks。Hook 可以直接拒絕呼叫或將其傳遞下去。返回
allow 的 hook 不會跳過下面的拒絕和詢問規則;無論 hook 結果如何,這些規則都會被評估。返回 allow 的 PreToolUse hook 也無法核准針對 關鍵路徑 的 rm 或 rmdir 移除。關於該 allow 在 plan mode 中的作用,請參閱 plan mode 中的 hook 核准。2
拒絕規則
檢查
deny 規則(來自 disallowed_tools 和 settings.json)。如果拒絕規則匹配,工具會被阻止,即使在 bypassPermissions 模式下也是如此。裸名稱拒絕規則(如 Bash)會在此評估開始前將工具從 Claude 的上下文中移除,因此只有作用域規則(如 Bash(rm *))會在此步驟中被檢查。3
詢問規則
檢查來自 settings.json 的
ask 規則。如果詢問規則匹配,呼叫會傳遞到您的 canUseTool 回呼 以進行確認,即使在 bypassPermissions 模式下也是如此。需要使用者互動的工具行為相同:AskUserQuestion 和 MCP 工具(其伺服器設定了 _meta["anthropic/requiresUserInteraction"])總是傳遞到回呼,即使當 allow 規則匹配時也是如此。在 dontAsk 模式下,兩種情況都會被拒絕,因為該模式永遠不會提示。MCP 註解需要 Claude Code v2.1.199 或更新版本。您的組織設定為 ask 的 claude.ai connector 工具也會在此步驟離開流程。每個呼叫都會傳遞到回呼,即使在 bypassPermissions 模式下,即使當 allow 規則匹配時也是如此。回呼會收到原因 Your organization requires approval for this tool。在 dontAsk 模式下,呼叫會被拒絕,因為該模式永遠不會提示。4
5
允許規則
檢查
allow 規則(來自 allowed_tools 和 settings.json)。如果規則匹配,工具會被批准。工具自行批准的呼叫也會在此步驟解決,無需規則:例如在您的工作目錄內的檔案讀取或 唯讀 Bash 命令。針對 關鍵路徑 的 rm 和 rmdir 移除永遠不會被 allow 規則核准。它們是否隨後到達您的回呼取決於權限模式:例如在 auto 模式的 Agent SDK 工作階段中,Claude Code 預設會拒絕它們而不呼叫它。關鍵路徑 模式表列出了每個模式對它們的處理方式。Allow 規則不會核准從 網路路徑 進行的讀取。6
canUseTool 回呼
如果上述任何步驟都未解決,請呼叫您的
canUseTool 回呼 以獲得決定。在 dontAsk 模式下,此步驟會被跳過,工具會被拒絕。在 TypeScript SDK 中,如果您設定了 permissionPrompts: 'none',您的回呼在此步驟不會被呼叫。PermissionRequest hook 仍然有機會決定,如果它不決定,Claude Code 會拒絕呼叫。此選項需要 Claude Code v2.1.259 或更新版本。canUseTool 回呼,SDK 會在構造查詢時發出一次 Node.js 程序警告。警告的代碼是 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED。兩個設定會觸發它:
permissionMode: 'bypassPermissions',它自動批准到達權限模式步驟的每個呼叫,除了 任何模式都不自動批准的操作- 每個裸
allowedTools條目,例如"Read",它在諮詢回呼之前自動核准整個工具,除了 任何模式都不自動核准的操作 和 從網路路徑進行的讀取
Bash(ls *))和 acceptEdits 模式不會觸發它,來自設定檔的 allow 規則對檢查不可見。
使用 process.on('warning', ...) 進行監聽並匹配代碼以記錄或抑制它。要無論模式和規則如何都控制每個工具呼叫,請改用 PreToolUse hook。
此頁面重點關注 allow 和 deny 規則 以及 權限模式。對於其他步驟:
- Hooks: 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 使用 hooks 控制執行。
- canUseTool 回呼: 在執行時提示使用者批准,當沒有較早的步驟解決呼叫時。請參閱 處理批准和使用者輸入。
允許和拒絕規則
allowed_tools 和 disallowed_tools(TypeScript:allowedTools / disallowedTools)在上述評估流程中新增允許和拒絕規則清單的項目。如果您在 allowed_tools 中命名其中一個任務追蹤工具,Claude Code 也會選擇加入該工作階段。任何未列在 allowed_tools 中的其他工具仍可供 Claude 使用,對其進行的需要批准的呼叫會進入權限模式。拒絕規則的行為取決於它們是命名工具還是在工具內限定模式。
允許規則僅在字面
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。請參閱讀取和編輯規則以了解四種錨定形式以及來自設定檔的規則如何解析。
對於鎖定的代理,將 allowedTools 與 permissionMode: "dontAsk" 配對:
default 模式中不需要核准的呼叫無論您是否列出都會執行,例如唯讀 Bash 命令、不在執行前詢問的工具(如 Agent),以及工作目錄內的檔案讀取。要將工具從請求中完全移除,請將其裸名稱新增到 disallowedTools。
您也可以在 .claude/settings.json 中以宣告方式設定允許、拒絕和詢問規則。當啟用 project 設定來源時會讀取這些規則,預設 query() 選項就是這樣。如果您明確設定 setting_sources(TypeScript:settingSources),請包含 "project" 以便它們適用。請參閱權限設定以了解規則語法。
權限模式
權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫query() 時設定權限模式,或在串流工作階段期間動態變更它。
如果您未設定權限模式,Claude Code 會根據工作階段開始時的模式中的規則選擇起始權限模式:
在自動模式中開始的工作階段會捨棄廣泛的允許規則,例如裸露的 Bash 項目,如自動模式如何評估動作所述。如果您的應用程式依賴 default 模式或此類規則,請明確傳遞 default。
在 TypeScript Agent SDK v0.3.286 之前,省略 permissionMode 與傳遞 default 相同。
可用模式
SDK 支援這些權限模式:設定權限模式
您可以在開始查詢時設定一次權限模式,或在工作階段進行中動態變更它。- 在查詢時
- 在串流期間
在建立查詢時傳遞
permission_mode(Python)或 permissionMode(TypeScript)。模式詳細資訊
接受編輯模式(acceptEdits)
自動核准檔案操作,讓 Claude 可以編輯程式碼而不會提示。其他工具(例如不是檔案系統操作的 Bash 命令)仍然需要正常權限。
自動核准的操作:
- 檔案編輯(Edit、Write 工具)
- 檔案系統命令:
mkdir、touch、rm、rmdir、mv、cp、sed
additionalDirectories 內的路徑。在 acceptEdits 模式中,當 Claude 執行以下操作時,Claude Code 不會自動核准請求:
- 在該範圍外的路徑上工作
- 寫入受保護的路徑
- 使用
rm或rmdir移除關鍵路徑
不要詢問模式(dontAsk)
將任何權限提示轉換為拒絕,而不呼叫 canUseTool。由 allowed_tools、settings.json 允許規則或 hook 預先核准的工具會正常執行,在 default 模式中不需要核准的呼叫也會執行,例如在您的工作目錄內的檔案讀取和對 Agent 的呼叫。您的組織設定為 ask 的連接器工具、需要使用者互動的工具、從網路路徑讀取,以及針對關鍵路徑的 rm 和 rmdir 移除即使符合允許規則也會被拒絕。PreToolUse hook 允許也不會清除關鍵路徑移除或從網路路徑讀取。
使用時機: 您想要為無頭代理提供固定、明確的工具表面,並偏好硬拒絕而非無聲依賴 canUseTool 不存在。
略過權限模式(bypassPermissions)
自動核准工具使用而不提示,除了下面警告中列出的情況。鉤子仍然執行,如果需要可以阻止操作。在 Linux 和 macOS 上,Claude Code 拒絕在此模式下以 root 身份或在已識別的沙箱外的 sudo 下啟動,查詢在第一個回合之前失敗。
規劃模式(plan)
Claude 探索程式碼庫並產生計畫,而不編輯您的原始檔案。唯讀工具的執行方式與在 default 權限模式中相同。
在 plan mode 中,檔案編輯永遠不會自動被核准,即使符合允許規則或 PreToolUse hook 傳回 allow。它們會改為透過您的 canUseTool 回呼提示。在 Claude Code v2.1.212 或更新版本上,修改檔案的 shell 命令(例如 touch 和 rm)會以相同方式到達您的 canUseTool 回呼。
在 TypeScript SDK 中,如果您在 permissionMode: 'plan' 旁邊設定 allowDangerouslySkipPermissions: true,檔案編輯和修改檔案的 shell 命令仍然會到達您的 canUseTool 回呼。此選項讓您稍後可以使用 setPermissionMode() 切換到 bypassPermissions。
Claude 可能會使用 AskUserQuestion 在最終確定計畫之前澄清需求。請參閱處理核准和使用者輸入以處理這些提示。
使用時機: 您想要 Claude 提議變更而不執行它們,例如在程式碼審查期間或當您需要在進行變更之前核准變更時。
自動模式(auto)
分類器模型會在 shell 命令和網路請求等動作執行之前檢閱它們,並允許或阻止它檢閱的每一個動作。如需了解自動模式所需的模型和提供者,以及它評估動作的順序,請參閱使用自動模式消除權限提示。
如果您使用 set_model()、setModel() 或 applyFlagSettings(),將處於自動模式的工作階段切換到自動模式不支援的模型,工作階段會變更為 default 模式:
- 您會看到的內容:一則子類型為
status且permissionMode設定為"default"的system訊息,TypeScript SDK 將其型別定義為SDKStatusMessage。從那時起,需要核准且不符合任何允許規則的呼叫會到達您的canUseTool回呼。 - 返回自動模式:切換到支援的模型,然後呼叫
set_permission_mode("auto")或setPermissionMode("auto")。如果您將模型切換回來而未進行該呼叫,工作階段會保持在default模式。當不支援的模型處於作用中時,該呼叫會失敗並顯示Cannot set permission mode to auto: auto mode unavailable for this model。
set_model()、setModel() 或 applyFlagSettings() 呼叫後變更為 default 模式,需要 Claude Code v2.1.299 或更新版本。
相關資源
如需了解權限評估流程中的其他步驟:- 處理核准和使用者輸入:互動式核准提示和澄清問題
- Hooks 指南:在代理程式生命週期中的關鍵點執行自訂程式碼
- 權限規則:
settings.json中的宣告式允許/拒絕規則