SpyBara
Go Premium

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

This page contains 48 additions and 46 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

設定權限

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

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

權限如何被評估

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

1. Hooks

首先執行 hooks。Hook 可以直接拒絕呼叫或將其傳遞下去。返回 allow 的 hook 不會跳過下面的拒絕和詢問規則；無論 hook 結果如何，這些規則都會被評估。

返回 allow 的 PreToolUse hook 也無法核准目標被 Claude Code 識別為關鍵路徑的 rm 或 rmdir 命令，例如 rm -rf ~。關於該 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. 權限模式

應用活躍的 權限模式：

  • 在 bypassPermissions 模式下，Claude Code 核准到達此步驟的所有內容，但經識別的關鍵路徑移除除外，這些會改為傳遞下去。
  • 在 acceptEdits 模式下，Claude Code 核准 接受編輯模式 下列出的檔案操作。
  • 在 plan 模式下，Claude Code 將檔案編輯和 shell 寫入工具發送到您的 canUseTool 回呼，無論 allow 規則如何，因此在規劃時寫入操作無法自動核准。
  • 在其他模式下，請求會傳遞下去。

5. 允許規則

檢查 allow 規則（來自 allowed_tools 和 settings.json）。如果規則匹配，工具會被核准。工具自行核准的呼叫也會在此步驟解決，無需規則：例如在您的工作目錄內的檔案讀取或 唯讀 Bash 命令。

經識別的關鍵路徑移除不會被 allow 規則核准。它們是否隨後到達您的回呼取決於權限模式：例如在 auto 模式的 Agent SDK 工作階段中，Claude Code 預設會拒絕它們而不呼叫它。關鍵路徑模式表列出了每個模式對它們的處理方式。

Allow 規則不會核准從 網路路徑 進行的讀取。

6. canUseTool 回呼

如果上述任何步驟都未解決，請呼叫您的 canUseTool 回呼 以獲得決定。在 dontAsk 模式下，此步驟會被跳過，工具會被拒絕，不過您安裝的 mod 仍可核准部分此類呼叫。

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

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

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

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

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

此頁面重點關注 allow 和 deny 規則 以及 權限模式。對於其他步驟：

允許和拒絕規則

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。請參閱讀取和編輯規則以了解四種錨定形式以及來自設定檔的規則如何解析。

[!WARNING]

自動批准的工具永遠不會到達 canUseTool。 在任何較早步驟中批准的工具呼叫，透過 acceptEdits 或 bypassPermissions，或透過允許規則，會跳過您的 canUseTool 回呼，因此您在那裡放置的權限檢查會被該工具無聲地繞過。

允許規則永遠不會自動核准 AskUserQuestion、標記為 _meta["anthropic/requiresUserInteraction"] 的 MCP 工具、您的組織設定為 ask 的連接器工具，或經辨識的 rm 和 rmdir 關鍵路徑移除。在 dontAsk 模式中，Claude Code 會拒絕這些呼叫而不呼叫回呼。在其他模式中，前三個會到達回呼。關鍵路徑模式表列出每個模式對關鍵路徑移除的處理方式。辨識這些移除的檢查可能會遺漏某些命令。

涵蓋範圍取決於項目的形式：像 Read 或 mcp__github__get_issue 這樣的裸名稱會自動核准對該工具的每個呼叫，除了上述例外情況和從網路路徑讀取，而像 Bash(npm test *) 這樣的限定規則只會自動核准符合的呼叫，其他需要核准的 Bash 呼叫仍會進入回呼。對於必須在每個工具呼叫上執行的檢查，請使用 PreToolUse hook：hook 在每個其他步驟之前執行，hook 拒絕即使在 bypassPermissions 模式中也適用。

對於鎖定的代理，將 allowedTools 與 permissionMode: "dontAsk" 配對：

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

列出的工具會被核准，但任何模式都不自動核准的動作和從網路路徑讀取除外。其他每個原本會提示的呼叫則會被拒絕，不過您安裝的 mod 仍可核准其中部分呼叫。

在 default 模式中不需要核准的呼叫無論您是否列出都會執行。這些呼叫包括唯讀 Bash 命令、不在執行前詢問的工具（如 Agent），以及工作目錄內的檔案讀取。要將工具從請求中完全移除，請將其裸名稱新增到 disallowedTools。

[!WARNING]

allowed_tools 不限制 bypassPermissions。 allowed_tools 預先批准您列出的工具。其他未列出的工具不符合任何允許規則，會進入權限模式，其中 bypassPermissions 會批准它們。將 allowed_tools=["Read"] 與 permission_mode="bypassPermissions" 一起設定仍會批准每個工具，包括 Bash、Write 和 Edit。如果您需要 bypassPermissions 但想要阻止特定工具，請使用 disallowed_tools。

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

權限模式

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

在 Claude Code v2.1.302 或更新版本中，除非您設定了權限模式，或應用程式從其設定檔中的 permissions.defaultMode 取得權限模式，否則您的應用程式會以 default 模式啟動。在 default 模式中，除非您透過允許規則、hook、canUseTool 回呼或權限提示工具核准，否則 Claude Code 會拒絕任何需要核准的工具呼叫。如果工具呼叫遭到拒絕，請參閱在 claude -p 和 Agent SDK 執行中工具呼叫遭拒。

可用模式

SDK 支援這些權限模式：

模式 說明 工具行為
default 標準權限行為 無模式型自動核准；需要核准且不符合任何允許規則的呼叫會觸發您的 canUseTool 回呼
dontAsk 拒絕而非提示 任何原本會提示的呼叫都會被拒絕，且不會呼叫 canUseTool，不過您安裝的 mod 仍可核准其中部分呼叫。由 allowed_tools 或 settings.json 允許規則核准的呼叫會執行，在 default 模式中不需要核准的呼叫也會執行。某些呼叫，例如從網路路徑讀取，即使符合 allowed_tools 或允許規則也會被拒絕。如需完整清單，請參閱不要詢問模式
acceptEdits 自動接受檔案編輯 檔案編輯和檔案系統操作（mkdir、rm、mv 等）會自動被核准
bypassPermissions 略過權限檢查 工具執行時不會出現權限提示，除了沒有任何模式自動核准的動作。請謹慎使用
plan 規劃模式 Claude 在不編輯您的原始檔案的情況下探索和規劃；檔案編輯永遠不會自動被核准，並透過您的 canUseTool 回呼提示
auto 模型分類核准 模型分類器檢閱殼層命令和網路請求等動作，允許或阻止它檢閱的每一個。請參閱 Auto 模式以了解可用性和決策順序

[!WARNING]

Subagent 繼承： 如果您的主工作階段處於 plan mode，其 AgentDefinition 設定 permissionMode: "acceptEdits" 的 subagent 仍會在 plan mode 中執行。該 subagent 對您原始檔案的 Edit 和 Write 呼叫仍會送往您的 canUseTool 回呼。plan mode 對您定義的 subagent 同樣有效，因此將工作交給 subagent 並不能繞過先檢閱計畫的步驟。

subagent 會從主工作階段繼承 plan、acceptEdits、auto 或 bypassPermissions，而在 default 或 dontAsk 模式的主工作階段下，它會以您設定的模式執行。即使如此，Claude Code 也永遠不會套用 "bypassPermissions" 值，且只有在該 subagent 可使用自動模式時才會套用 "auto" 值。bypassPermissions 例外需要 Claude Code v2.1.267 或更新版本。

子代理可能具有不同的系統提示和比您的主代理更少受限的行為，因此繼承 bypassPermissions 會授予它們完整的自主系統存取權。沒有任何模式自動核准的動作仍然適用。

設定權限模式

您可以在開始查詢時設定一次權限模式，或在工作階段進行中動態變更它。

在查詢時

在建立查詢時傳遞 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())

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）以在工作階段中途變更模式。新模式會立即對所有後續工具請求生效。這讓您可以從限制性開始，並隨著信任建立而放寬權限，例如在檢閱 Claude 的初始方法後切換到 acceptEdits。

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

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 內的路徑。在 acceptEdits 模式中，當 Claude 執行以下操作時，Claude Code 不會自動核准請求：

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

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

不要詢問模式（dontAsk）

將任何權限提示轉換為拒絕，而不呼叫 canUseTool，不過您安裝的 mod 仍可核准其中部分呼叫。由 allowed_tools、settings.json 允許規則或 hook 預先核准的工具會正常執行。在 default 模式中不需要核准的呼叫也會執行，例如在您的工作目錄內的檔案讀取和對 Agent 的呼叫。

您的組織設定為 ask 的連接器工具、需要使用者互動的工具、從網路路徑讀取，以及已識別的關鍵路徑移除即使符合允許規則也會被拒絕。PreToolUse hook 允許也不會清除已識別的關鍵路徑移除或從網路路徑讀取。識別這些移除的檢查可能會遺漏某些命令。

使用時機： 您想要為無頭代理提供固定、明確的工具表面，並偏好硬拒絕而非無聲依賴 canUseTool 不存在。

略過權限模式（bypassPermissions）

自動核准工具使用而不提示，除了下面警告中列出的情況。鉤子仍然執行，如果需要可以阻止操作。在 Linux 和 macOS 上，Claude Code 拒絕在此模式下以 root 身份或在已識別的沙箱外的 sudo 下啟動，查詢在第一個回合之前失敗。

[!WARNING]

請極其謹慎使用。Claude 在此模式中具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。

allowed_tools 不會限制此模式。每個工具都會被核准，而不僅僅是您列出的工具。這些控制仍然適用：

規劃模式（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 或更新版本。

相關資源

如需了解權限評估流程中的其他步驟：