> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 権限ポリシー

> ツール呼び出しを許可・確認・拒否のいずれにするか制御する。

権限ポリシーは、Agent がツールを呼び出す際の挙動を制御します。組み込みツールと MCP ツールの呼び出しは `allow`、`ask`、`deny` のいずれかとして評価されます。クライアントサイドのカスタムツールは常に一時停止し、アプリケーションが実行して結果を返します。

## ランタイムの挙動

ツール呼び出しがイベントストリームに送出される際の挙動:

| イベント                    | 意味                     | 主要フィールド                                                          |
| ----------------------- | ---------------------- | ---------------------------------------------------------------- |
| `agent.tool_use`        | 組み込みツール呼び出し            | `id`, `name`, `input`, `evaluated_permission`                    |
| `agent.mcp_tool_use`    | MCP ツール呼び出し            | `id`, `name`, `input`, `mcp_server_name`, `evaluated_permission` |
| `agent.custom_tool_use` | クライアントサイドのカスタムツールリクエスト | `id`, `name`, `input`                                            |

`evaluated_permission` の値:

| 値       | 挙動                                     |
| ------- | -------------------------------------- |
| `allow` | プラットフォームがツールを直接実行                      |
| `ask`   | ターンが一時停止し、`user.tool_confirmation` を待機 |
| `deny`  | プラットフォームが拒否されたツール結果を Agent に返却         |

カスタムツールは `permission_policy` をサポートしません。クライアント側で実行し、`user.custom_tool_result` で応答してください。

## Agent でのポリシー設定

組み込みツールと MCP ツールの権限は、Agent の `tools` 配列で構成します：

```json theme={null}
{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write"],
      "configs": [
        {"name": "Read", "permission_policy": {"type": "always_allow"}},
        {"name": "Write", "permission_policy": {"type": "always_ask"}},
        {"name": "Bash", "permission_policy": {"type": "always_deny"}}
      ]
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "weather-service",
      "configs": [
        {"name": "get_forecast", "permission_policy": {"type": "always_ask"}}
      ]
    }
  ]
}
```

| 設定箇所                                  | 対象     | 説明                                                                                 |
| ------------------------------------- | ------ | ---------------------------------------------------------------------------------- |
| `tools[].configs[].permission_policy` | 個別のツール | ツールごとのオーバーライド。組み込みツールの場合 `name` は `Read` などの組み込みツール名、MCP ツールの場合は MCP サーバーが公開するツール名 |
| `tools[].configs[].enabled`           | 個別のツール | `false` に設定してツールを無効化・拒否。`enabled_tools` を使用している場合は、無効化するツールをホワイトリストから除外            |

`permission_policy.type` の値:

| 値              | ランタイム結果                                                             |
| -------------- | ------------------------------------------------------------------- |
| `always_allow` | `evaluated_permission: "allow"`                                     |
| `always_ask`   | `evaluated_permission: "ask"` となり、ターンは `user.tool_confirmation` を待機 |
| `always_deny`  | `evaluated_permission: "deny"`                                      |

## Pending Action フロー

ツール呼び出しに人間またはクライアントの入力が必要な場合:

1. ストリームが `agent.tool_use` または `agent.custom_tool_use` を送出
2. ストリームが `session.status_idle`（`stop_reason.type: "requires_action"`）を送出
3. `stop_reason.event_ids` に応答が必要なイベント ID が列挙される
4. クライアントが `POST /api/v1/cloud/sessions/{session_id}/events` に応答イベントを送信
5. Agent が同じターンを続行

```json theme={null}
{
  "type": "session.status_idle",
  "status": "idle",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["evt_01JZ6Q3FB6SG8F7J1M2N"]
  }
}
```

Pending Action は自動的にタイムアウトしません。クライアントが応答するか、セッション/ターンがキャンセルされるまで保留状態が維持されます。

## ツール呼び出しの確認

`agent.tool_use` イベントの `id` を `tool_use_id` として使用します。これは `evt_...` 形式のイベント ID であり、モデルプロバイダー内部のツール使用 ID ではありません。

<Tabs>
  <Tab title="承認">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "events": [
          {
            "type": "user.tool_confirmation",
            "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
            "result": "allow"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="拒否">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "events": [
          {
            "type": "user.tool_confirmation",
            "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
            "result": "deny",
            "deny_message": "ファイルの参照のみ行い、削除しないでください。"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

## カスタムツールの完了

カスタムツールは Agent の `type: "custom"` で構成します。詳細は [Agent ツール](/ja/cloud-agents/tools) を参照してください。Agent がカスタムツールをリクエストした場合、アプリケーション側で実行し、`agent.custom_tool_use` のイベント ID を使って応答します：

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.custom_tool_result",
        "custom_tool_use_id": "evt_01JZ6R1V9Z8K2M3N4P5Q",
        "content": [{"type": "text", "text": "注文ステータス: 発送済み"}]
      }
    ]
  }'
```

`content` の値は文字列、単一のテキストブロック、またはテキストブロックの配列で指定できます。返されたイベントはコンテンツブロック形式で格納されます。

## よくある質問

**Q: 1 つのターンで複数の応答が必要になることはありますか?** A: あります。`stop_reason.event_ids` に複数のイベント ID が含まれる場合があります。保留中の各ツールリクエストに応答してください。

**Q: Pending Action にタイムアウトはありますか?** A: ありません。応答されるか、セッション/ターンがキャンセルされるまで保留状態が維持されます。

**Q: カスタムツールに `permission_policy` を使用できますか?** A: できません。カスタムツールはクライアントサイドで実行されるため、実行の可否はクライアントが判断します。

## 次のステップ

<CardGroup cols={2}>
  <Card title="Agent ツール" icon="wrench" href="/ja/cloud-agents/tools">
    組み込み、MCP、カスタムツールを構成する。
  </Card>

  <Card title="Session イベントストリーム" icon="wave-pulse" href="/ja/cloud-agents/events-stream">
    `agent.tool_use` と確認イベントを購読する。
  </Card>

  <Card title="Session の開始" icon="play" href="/ja/cloud-agents/sessions">
    実行中のターンでツール確認を行う。
  </Card>

  <Card title="Agent の定義" icon="user-gear" href="/ja/cloud-agents/define-agent">
    `tools` と `configs` を含む Agent 構成全体のおさらい。
  </Card>
</CardGroup>