権限ポリシー

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



次のステップ