権限ポリシー

権限ポリシーは、サーバー側で実行されるツール（事前構築されたエージェントツールセットとMCPツールセット）が自動的に実行されるか、承認を待つかを制御します。カスタムツールはアプリケーション側で実行され、ユーザー自身が制御するため、権限ポリシーの対象外です。



権限ポリシーの種類

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

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



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

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



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

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

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

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 <<'YAML'
name: Dev Assistant
model: claude-opus-4-8
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
YAML



個別のツールポリシーをオーバーライドする

configs配列を使用して、個々のツールのデフォルトをオーバーライドします。エージェントツールセットのnameの値は利用可能なツールに記載されています。次の例では、エージェントツールセット全体をデフォルトで許可しますが、bashコマンドの実行前には確認を必須とします。

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
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を返す前にそれを実行するかどうかを判断する責任があります。完全なフローについてはセッションイベントストリームを参照してください。



次のステップ