権限ポリシー

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



次のステップ