権限ポリシー

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

権限ポリシーの種類

ツールセットの種類ごとに独自のデフォルトがあります。エージェントツールセットのデフォルトは always_allow、MCPツールセットのデフォルトは always_ask です。

権限ポリシーは、有効化されたツールがいつ実行されるかを制御します。ツールをエージェントから完全に取り除くには、代わりにそのツールを無効化してください。特定のツールを無効化するを参照してください。

ツールセットにポリシーを設定する

権限ポリシーは、エージェント作成時にエージェントの tools 設定で指定します。後からエージェントを更新することで変更することもできます。実行中のセッションは、作成時のツールセット設定を保持します。更新はその後に作成されたセッションに適用されます。

エージェントツールセットの権限

エージェントを作成する際、default_config.permission_policy を使用して agent_toolset_20260401 内のすべてのツールにポリシーを適用できます。

ant beta:agents create < agent.yaml

name: Coding Assistant
model: claude-opus-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 beta:agents create < agent.yaml

name: Dev Assistant
model: claude-opus-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 beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
YAML

この tools 設定をエージェント作成リクエストで渡します（CLIタブに完全なコマンドが示されています）。MCPツールセットも同じツール単位の上書きをサポートしており、name にはMCPサーバーが報告するツール名を設定します。利用可能なMCPツールを設定するを参照してください。

確認リクエストに応答する

エージェントが always_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 を含む）を受け取ります。

以下の例では、ツール使用イベントのIDは session.status_idle イベントの stop_reason.event_ids 配列から取得しています。イベントの受信について詳しくはセッションイベントストリームガイドを参照してください。また、セッションが入力待ちで一時停止したときに通知を受け取るにはWebhookをサブスクライブしてください。

# ツールの実行を許可する
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# または説明を付けて拒否する
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{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 を返す前にそれを実行するかどうかを判断する責任を負います。完全なフローについてはセッションイベントストリームを参照してください。

次のステップ