權限政策

「Permission policies」（權限政策）控制由伺服器執行的工具（預先建置的代理程式工具集與 MCP 工具集）是自動執行、等待您的核准，還是由伺服器逐一評估每次呼叫。「Custom tools」（自訂工具）由您的應用程式執行並由您控制，因此不受權限政策管轄。

權限政策類型

每種工具集類型都有各自的預設值：代理工具集預設為 always_allow，MCP 工具集預設為 always_ask。

權限政策控制已啟用的工具何時執行。若要將某個工具從代理中完全移除，請改為停用該工具。請參閱停用特定工具。

為工具集設定政策

您在建立代理時，於代理的 tools 設定中設定權限政策，之後可以透過更新代理來變更。執行中的工作階段會保留其建立時的工具集設定。更新會套用至之後建立的工作階段。

代理工具集權限

建立代理時，您可以使用 default_config.permission_policy 將政策套用至 agent_toolset_20260401 中的每個工具：

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
---

default_config 為選用項目。若您省略它，代理工具集會以預設權限政策 always_allow 啟用。

MCP 工具集權限

MCP 工具集預設為 always_ask。這可確保新增至 MCP 伺服器的新工具不會在未經核准的情況下於您的應用程式中執行。若要自動核准來自受信任 MCP 伺服器的工具，請在 mcp_toolset 項目上設定 default_config.permission_policy。

mcp_server_name 必須與 mcp_servers 陣列中某個伺服器的 name 相符。

此範例連接一個 GitHub MCP 伺服器，並允許其工具在無需確認的情況下執行：

ant apply agent.md

---
name: Dev Assistant
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: always_allow
---

覆寫個別工具的政策

使用 configs 陣列來覆寫個別工具的預設值。代理工具集的 name 值列於可用工具中。此範例預設允許完整的代理工具集，但在執行任何 bash 指令前需要確認：

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
---

請在代理建立請求中傳入此 tools 設定（CLI 分頁顯示完整指令）。MCP 工具集支援相同的逐工具覆寫，其中 name 設為 MCP 伺服器回報的工具名稱。請參閱設定可用的 MCP 工具。

使用 auto 讓伺服器評估每次呼叫

使用 auto 權限政策時，伺服器會在每次呼叫執行前進行評估。由於評估會考量工具、呼叫的輸入，以及工作階段截至當時為止的內容，伺服器可能會以不同方式處理對同一工具的兩次呼叫。每次呼叫會有以下三種結果之一：

• 呼叫會執行。 當伺服器判定呼叫是安全的，工具會如同在 always_allow 下一樣執行。
• 呼叫會被拒絕。 當伺服器將呼叫評估為高風險時，工具不會執行。代理程式會收到一個錯誤工具結果，其內容為 Permission to use {tool_name} has been denied. 且 is_error: true。工作階段會繼續執行，而您的用戶端無法覆寫此拒絕。
• 呼叫會暫停以等待您的核准。 當伺服器無法做出判定時，工作階段會如同在 always_ask 下一樣暫停。請參閱回應確認請求。

若要啟用 auto，請將 permission_policy 設為 {"type": "auto"}。它的設定位置與其他政策相同的兩處：工具集的 default_config（套用至整個工具集），或 configs 項目（套用至單一工具）。代理程式工具集與 MCP 工具集都接受此設定。沒有任何工具集預設使用 auto。

以下範例將 auto 設為代理程式工具集與 github MCP 工具集的預設值，並將 bash 覆寫為 always_ask：

ant apply agent.md

---
name: Ops Agent
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: auto
    configs:
      - name: bash
        permission_policy:
          type: always_ask
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: auto
---

您在 user.message 事件中發布的內容會被視為您的意圖，這可能使伺服器允許原本會拒絕的呼叫。伺服器不會從工具結果、擷取的網頁、MCP 伺服器的回應，或工作階段執行緒之間的訊息中讀取意圖。伺服器會評估這些內容，但不會從中接受指示。無論由誰提出請求，伺服器都會將某些呼叫評估為高風險。如果您在 user.message 事件中轉送不受信任的終端使用者輸入，伺服器也會將該輸入視為您的意圖，而這可能使某個呼叫獲得允許。對於您不希望該終端使用者在未經審查的情況下執行的工具，請設定 always_ask。

查看每次呼叫的評估方式

在任何權限政策下，每個 agent.tool_use 與 agent.mcp_tool_use 事件都帶有 evaluated_permission，即該呼叫權限檢查的結果："allow"、"ask" 或 "deny"。大多數事件也帶有一個 evaluation 物件，其 type 指出產生該結果的政策。在 auto 下，該物件還會記錄伺服器的判定，並在結果為 ask 或 deny 時附上 reason_code。

例如，當 bash 處於 auto 下，且伺服器將某次呼叫評估為高風險時，被拒絕的呼叫會以如下形式出現在事件串流中：

{
  "type": "agent.tool_use",
  "id": "sevt_01pqr...",
  "name": "bash",
  "input": {
    "command": "rm -rf /workspace/reports"
  },
  "evaluated_permission": "deny",
  "evaluation": {
    "type": "auto",
    "evaluated_permission": {
      "type": "deny",
      "reason_code": "high_risk"
    }
  },
  "processed_at": "2026-03-25T14:05:12Z"
}

evaluation 物件會採用下表中的其中一種形式。

當 evaluation.type 為 "auto" 時，其巢狀的 evaluated_permission.type 會重複事件頂層的 evaluated_permission，因此您可以從任一欄位讀取結果。reason_code 是供您的用戶端進行分支判斷並保存於稽核紀錄中的值，而非用於向終端使用者顯示的文字。

在兩種情況下不會有 evaluation。當代理程式指定了一個未在工作階段中啟用的工具時，伺服器會在不評估政策的情況下拒絕該呼叫：事件會帶有 evaluated_permission: "deny" 且沒有 evaluation。在引入 evaluation 之前記錄的事件也會省略它：當 evaluated_permission 為 "allow" 時，請將其視為 always_allow；當其為 "ask" 時，請將其視為 always_ask。

請讓您的用戶端能夠容忍無法辨識的 evaluation.type 或 reason_code。agent.custom_tool_use 事件不帶有這兩個欄位，因為權限政策不管轄自訂工具。

回應確認請求

在 always_ask 政策下，或在 auto 下伺服器無法做出判定時，工具呼叫會評估為 ask。發生這種情況時：

1. 工作階段會發出 agent.tool_use 或 agent.mcp_tool_use 事件。
2. 工作階段會以 session.status_idle 事件暫停，其 stop_reason.type 為 requires_action。造成阻擋的事件 ID 位於 stop_reason.event_ids 陣列中。工作階段會無限期等待回應。
3. 針對每個造成阻擋的事件傳送一個 user.tool_confirmation 事件，並在 tool_use_id 參數中傳入該事件 ID。將 result 設為 "allow" 或 "deny"。使用 deny_message 說明拒絕原因。您可以在單一 events 請求中傳送多個確認。
4. 一旦所有造成阻擋的事件都已解決，工作階段會轉換回 running。獲允許的工具會執行。遭拒絕的工具不會執行，且代理會收到一個工具結果，說明該呼叫已被拒絕，其中包含您的 deny_message。

如果您針對 evaluated_permission 不是 ask 的事件傳送 user.tool_confirmation，API 會以 400 錯誤拒絕。這包括伺服器在 auto 下拒絕的呼叫：您的用戶端無法覆寫它們。

若要改以互動方式回應，請使用 ant beta:sessions connect，它會顯示等待中的呼叫，並在您允許或拒絕時傳送此事件。請參閱從終端機連接至 Managed Agents 工作階段。

在以下範例中，工具使用事件 ID 來自 session.status_idle 事件的 stop_reason.event_ids 陣列。請在工作階段事件串流指南中進一步了解如何接收事件，或訂閱 webhooks 以便在工作階段暫停等待輸入時收到通知。

# 允許工具執行
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# 或拒絕並附上說明
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": mcp_tool_use_event.id,
            "result": "deny",
            "deny_message": "Don't create issues in the production project. Use the staging project.",
        },
    ],
)

自訂工具

權限政策不適用於自訂工具。當代理呼叫自訂工具時，您的應用程式會收到 agent.custom_tool_use 事件，並負責在傳回 user.custom_tool_result 之前決定是否執行該工具。完整流程請參閱工作階段事件串流。

後續步驟