SpyBara
Go Premium

agent-sdk/permissions.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 50 additions and 31 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Fri 25 23:58

設定權限

使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理程式如何使用工具。

Claude Agent SDK 提供權限控制來管理 Claude 如何使用工具。使用權限模式和規則來定義自動允許的內容，並使用 canUseTool 回呼 在執行時處理其他所有情況。

權限如何被評估

當 Claude 請求工具時，SDK 會按照以下順序檢查權限：

1

Hooks

首先執行 hooks。Hook 可以直接拒絕呼叫或將其傳遞。返回 allow 的 hook 不會跳過下面的拒絕和詢問規則；無論 hook 結果如何，這些規則都會被評估。返回 allow 的 PreToolUse hook 也無法批准針對關鍵路徑的 rm 或 rmdir 移除。

2

拒絕規則

檢查 deny 規則（來自 disallowed_tools 和 settings.json）。如果拒絕規則符合，工具會被阻止，即使在 bypassPermissions 模式下也是如此。裸名稱拒絕規則（如 Bash）會在此評估開始前將工具從 Claude 的上下文中移除，因此只有範圍規則（如 Bash(rm *)）會在此步驟中被檢查。

3

詢問規則

檢查來自 settings.json 的 ask 規則。如果詢問規則符合，呼叫會傳遞到您的 canUseTool 回呼 以進行確認，即使在 bypassPermissions 模式下也是如此。

需要使用者互動的工具行為相同：AskUserQuestion 和 MCP 工具（其伺服器設定 _meta["anthropic/requiresUserInteraction"]）總是會傳遞到回呼，即使允許規則符合時也是如此。在 dontAsk 模式下，兩種情況都會被拒絕，因為該模式永遠不會提示。MCP 註解需要 Claude Code v2.1.199 或更新版本。

claude.ai 連接器 工具（您的組織已設定為 ask）也會在此步驟離開流程。每個呼叫都會傳遞到回呼，即使在 bypassPermissions 模式下，即使允許規則符合時也是如此。回呼會收到原因 Your organization requires approval for this tool。在 dontAsk 模式下，呼叫會被拒絕，因為該模式永遠不會提示。

4

權限模式

應用活躍的權限模式：

  • 在 bypassPermissions 模式下，Claude Code 批准到達此步驟的所有內容，除了針對關鍵路徑的 rm 和 rmdir 移除，這些會傳遞到回呼。
  • 在 acceptEdits 模式下，Claude Code 批准接受編輯模式下列出的檔案操作。
  • 在 plan 模式下，Claude Code 將檔案編輯和 shell 寫入工具傳送到您的 canUseTool 回呼，無論允許規則如何，因此在規劃時寫入操作無法自動批准。
  • 在其他模式下，請求會傳遞到回呼。
5

允許規則

檢查 allow 規則（來自 allowed_tools 和 settings.json）。如果規則符合，工具會被批准。針對關鍵路徑的 rm 和 rmdir 移除永遠不會被允許規則批准：它們在提示的模式下到達您的回呼，在 Claude Code v2.1.218 或更新版本的 auto 模式下進入分類器，並在 dontAsk 模式下被拒絕。

6

canUseTool 回呼

如果上述任何步驟都未解決，請呼叫您的 canUseTool 回呼 以做出決定。在 dontAsk 模式下，此步驟會被跳過，工具會被拒絕。

在 TypeScript SDK 中，如果您設定 permissionPrompts: 'none'，您的回呼在此步驟不會被呼叫。PermissionRequest hook 仍然有機會做出決定，如果它沒有，Claude Code 會拒絕呼叫。此選項需要 Claude Code v2.1.259 或更新版本。

六步驟權限評估流程圖，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到'已阻止'；權限模式繞過、允許規則和 canUseTool 可以路由到'執行'；詢問規則路由到 canUseTool。 六步驟權限評估流程圖，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到'已阻止'；權限模式繞過、允許規則和 canUseTool 可以路由到'執行'；詢問規則路由到 canUseTool。

如果您在 TypeScript SDK 預期評估順序會在諮詢回呼之前自動批准呼叫的配置中傳遞 canUseTool 回呼，SDK 會在建構查詢時發出一次 Node.js 程序警告。警告的代碼是 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED。兩種配置會觸發它：

具有指定符的項目（例如 Bash(ls *)）和 acceptEdits 模式不會觸發它，來自設定檔的允許規則對檢查不可見。

使用 process.on('warning', ...) 進行監聽，並匹配代碼以記錄或抑制它。若要無論模式和規則如何都控制每個工具呼叫，請改用 PreToolUse hook。

本頁重點關注 允許和拒絕規則 以及 權限模式。對於其他步驟：

允許和拒絕規則

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。其他 Bash 呼叫（包括 /bin/rm）會通過權限模式。
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"
};

您也可以在 .claude/settings.json 中宣告式地設定允許、拒絕和詢問規則。當啟用 project 設定來源時，這些規則會被讀取，預設 query() 選項就是這樣。如果您明確設定 setting_sources（TypeScript：settingSources），請包含 "project" 以便它們適用。請參閱 權限設定 以了解規則語法。

權限模式

權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 query() 時設定權限模式，或在串流會話期間動態更改它。

可用模式

SDK 支援這些權限模式：

模式 描述 工具行為
default 標準權限行為 無自動批准；不符合的工具會觸發您的 canUseTool 回呼
dontAsk 拒絕而不是提示 任何未被 allowed_tools 或規則預先批准的內容都會被拒絕；連接器工具您的組織設定為 ask和需要使用者互動的工具即使您已預先批准它們也會被拒絕，rm 和 rmdir 移除針對關鍵路徑的操作也會被拒絕。canUseTool 永遠不會被呼叫
acceptEdits 自動接受檔案編輯 檔案編輯和檔案系統操作（mkdir、rm、mv 等）會自動被批准
bypassPermissions 繞過權限檢查 工具執行時無需權限提示，除了任何模式都不會自動批准的操作。謹慎使用
plan 規劃模式 Claude 在不編輯您的原始檔案的情況下探索和規劃；檔案編輯永遠不會自動批准，並透過您的 canUseTool 回呼提示
auto 模型分類批准 模型分類器批准或拒絕權限提示。請參閱 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 執行以下操作時，Claude Code 不會自動批准請求：

  • 在該範圍外的路徑上工作
  • 寫入受保護的路徑
  • 使用 rm 或 rmdir 移除關鍵路徑

使用時機： 您信任 Claude 的編輯並想要更快的迭代，例如在原型設計期間或在隔離目錄中工作時。

不詢問模式（`dontAsk`）

將任何權限提示轉換為拒絕。由 allowed_tools、settings.json 允許規則或作為 hook 執行的工具會正常執行。連接器工具您的組織設定為 ask、需要使用者互動的工具，以及 rm 和 rmdir 移除針對關鍵路徑的操作即使允許規則符合也會被拒絕。PreToolUse hook 允許也不會清除關鍵路徑移除。其他所有內容都會被拒絕，而不呼叫 canUseTool。

使用時機： 您想要為無頭代理程式提供固定的明確工具表面，並且更喜歡硬拒絕而不是無聲依賴 canUseTool 不存在。

繞過權限模式（`bypassPermissions`）

自動批准工具使用而無需提示，除了下方警告中列出的情況。Hooks 仍然執行，如果需要可以阻止操作。

規劃模式（`plan`）

Claude 探索程式碼庫並產生計畫而不編輯您的原始檔案。唯讀工具在 default 權限模式中執行。

檔案編輯在規劃模式下永遠不會自動批准，即使允許規則符合。它們改為透過您的 canUseTool 回呼提示。在 Claude Code v2.1.212 或更新版本上，修改檔案的 shell 命令（例如 touch 和 rm）會以相同方式到達您的 canUseTool 回呼。

Claude 可能會使用 AskUserQuestion 在最終確定計畫之前澄清需求。請參閱處理核准和使用者輸入以處理這些提示。

使用時機： 您想要 Claude 提出變更建議而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。

對於權限評估流程中的其他步驟：