権限ポリシー

「permission policies」（権限ポリシー）は、サーバーで実行されるツール（事前構築済みのエージェントツールセットとMCPツールセット）を自動的に実行するか、承認を待つか、あるいは各呼び出しをサーバーに評価させるかを制御します。カスタムツールはアプリケーションによって実行され、利用者自身が制御するため、権限ポリシーの対象にはなりません。

権限ポリシーの種類

ツールセットの種類ごとに独自のデフォルトがあります。エージェントツールセットのデフォルトは 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権限ポリシーでは、サーバーが各呼び出しを実行前に評価します。評価ではツール、呼び出しの入力、およびその時点までのセッションの内容が考慮されるため、サーバーは同じツールへの2つの呼び出しを異なる形で扱うことがあります。各呼び出しの結果は次の3つのいずれかになります。

• 呼び出しが実行される。 サーバーが呼び出しを安全と判断した場合、ツールはalways_allowの場合と同様に実行されます。
• 呼び出しが拒否される。 サーバーが呼び出しを高リスクと評価した場合、ツールは実行されません。エージェントは、内容がPermission to use {tool_name} has been denied.でis_error: trueのエラーツール結果を受け取ります。セッションは実行を継続し、クライアントはこの拒否を覆すことはできません。
• 呼び出しが承認待ちで一時停止する。 サーバーが判断に至らなかった場合、セッションはalways_askの場合と同様に一時停止します。確認リクエストに応答するを参照してください。

autoを有効にするには、permission_policyを{"type": "auto"}に設定します。設定場所は他のポリシーと同じ2か所で、ツールセット全体に対してはツールセットのdefault_config、1つのツールに対してはconfigsエントリです。エージェントツールセットとMCPツールセットのどちらでも使用できます。デフォルトでautoを使用するツールセットはありません。

次の例では、エージェントツールセットとgithub MCPツールセットのデフォルトとしてautoを設定し、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イベントで送信した内容は利用者の意図として扱われ、サーバーが本来なら拒否する呼び出しを許可する根拠になることがあります。サーバーは、ツール結果、取得したWebページ、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が存在しないケースは2つあります。エージェントがセッションで有効化されていないツールを指定した場合、サーバーはポリシーを評価せずに呼び出しを拒否します。このとき、イベントには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. セッションは、stop_reason.type が requires_action である session.status_idle イベントとともに一時停止します。ブロックしているイベントのIDは stop_reason.event_ids 配列に含まれます。セッションは応答を無期限に待機します。
3. ブロックしている各イベントに対して user.tool_confirmation イベントを送信し、tool_use_id パラメータにイベントIDを渡します。result を "allow" または "deny" に設定します。拒否の理由を説明するには deny_message を使用します。1回の 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 配列から取得しています。イベントの受信について詳しくはセッションイベントストリームガイドを参照してください。また、セッションが入力待ちで一時停止したときに通知を受け取るにはWebhookをサブスクライブしてください。

# ツールの実行を許可する
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 を返す前にそれを実行するかどうかを判断する責任を負います。完全なフローについてはセッションイベントストリームを参照してください。

次のステップ