権限ポリシー

「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配列に含まれます。セッションは応答を無期限に待ちます。ワークフロー実行のスレッドからの呼び出しは、プライマリストリーム上でクライアントに届きます。セッション内で他の処理が動作している間、セッションはrunningのままでsession.status_idleを送信しないことがあるため、ツール使用イベント自体に応答してください。呼び出しが待機するのは、実行がそのスレッドの処理を終えるか、実行が終了するまでです。中断によって待機状態のまま残る可能性があるため、自分で許可または拒否してください。
3. ブロックしている各イベントに対してuser.tool_confirmationイベントを送信し、tool_use_idパラメータにイベントIDを渡します。resultを"allow"または"deny"に設定します。拒否の理由を説明するにはdeny_messageを使用します。1回のeventsリクエストで複数の確認を送信できます。
4. ブロックしているすべてのイベントが解決されると、セッションはrunningに戻ります。許可されたツールは実行されます。拒否されたツールは実行されず、エージェントは呼び出しが拒否されたことを示すツール結果を受け取ります。この結果にはdeny_messageが含まれます。

たとえば、always_askポリシーの下で一時停止したbash呼び出しは、ストリーム上で次のように表示されます。

{
  "type": "agent.tool_use",
  "id": "sevt_01def...",
  "name": "bash",
  "input": {
    "command": "pip install -r requirements.txt"
  },
  "evaluated_permission": "ask",
  "evaluation": {
    "type": "always_ask"
  },
  "processed_at": "2026-03-25T14:01:45Z"
}

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

次のステップ