権限

エージェントの権限は 3 つの層からなる。プロファイルが定めるツールと権限モード、人が答える権限リクエスト、そしてエージェントを管理し認証情報の名前を紐付ける人である。

ツール: プロファイルが決める見出しのリンクをコピー

セッションは、プロファイルの tools に含まれるツールだけを使う。プロファイルがブロックした組み込みツール (deny) は tools に入らない。それ以外のツールは権限リクエストなしで拒否され、モデルはエラーの tool_result を受け取る。何をブロックするかはプロファイルを選ぶにある。次のスクリプトは、ローカルプロファイルがブロックした WebFetch を呼び出す (ローカルプロファイルの deny は ["NotebookEdit","WebFetch","WebSearch"] である)。

created=$(curl -sS "$API/v1/sessions" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "$(jq -nc --arg m 'GATE-SPEC {"id":"outside","steps":[{"tool":"WebFetch","input":{"url":"https://example.com","prompt":"summarize"}}],"final":"done"}' \
    '{profile_id: "claude-coding-local", repository_id: "sample-app", message: $m}')")
SID=$(echo "$created" | jq -r .session_id)
until [ "$(curl -sS "$API/v1/sessions/$SID/turns/1" -H "Authorization: Bearer $KEY" | jq -r .status)" = completed ]; do
  sleep 2
done
curl -sSN --max-time 5 "$API/v1/sessions/$SID/events" -H "Authorization: Bearer $KEY" \
  | awk '/^event: tool_result/ { getline; sub(/^data: /, ""); print }' \
  | jq -c '.data | {is_error, content}' || true

curl: (28) Operation timed out after 5006 milliseconds with 4482 bytes received
{"is_error":true,"content":"<tool_use_error>Error: No such tool available: WebFetch. WebFetch is disabled for this session, in subagents as well as here.</tool_use_error>"}

curl: (28) は --max-time がストリームを切断したものである。

リリースから作ったセッションはさらに狭く、そのリリースに固定されたツールだけを使う。カードの capabilities.tools (null ならリリース作成時にプロファイルがブロックしていないツールすべて) から forbidden を除いた一覧で、リリースのレスポンスの effective_tools.tools がその一覧である。カードに Read だけを書くと、セッションは Read だけを使い、ほかの組み込みツールは上と同じく拒否される。リリースなしで作ったセッションは、プロファイルのツールをすべて使う。

ブロックする場所は二つあり、範囲が違う。

カードはプロファイルがブロックしたツールを開けない。プロファイルがブロックしたツールをカードの capabilities.tools に書くと、リリースを作るときに拒否される。

カードの tool_policy では、組み込みツールの既定値は allow、MCP ツールの既定値は ask である。組み込みツールを実行前に人に確認させるのはこの値ではなく権限モードである。組み込みツールをまったく使わせないには、プロファイルの deny かカードの forbidden でブロックする。

権限モード見出しのリンクをコピー

プロファイルの permission_mode が、ツールを実行する前に人へ尋ねるかどうかを決める。セッション詳細の runtime.permission_mode に表示される。

モードはカタログにのみ存在し、セッションのリクエストで変更することはできない。コンソールで新しく作るプロファイルは、ベースが許せば auto から始まる。すでに default で作ったプロファイルは自動では移さない。push と PR のツールは、最新の worker では plan を除くモードでエンジンが尋ねない(plan は従来どおりエンジンが尋ねる)。Bash などエンジンのツールまでエージェントが尋ねないようにするには、auto のバージョンを作り、エージェントの新しい release がそれを使うようにする。運用担当者のプロファイルなら、owner が詳細の新しいバージョンで権限モードを auto にして保存する。ワークスペースプロファイルはベースより広いモードを選べないので、ベースが auto を許すなら編集で auto を保存し、ベースが default なら auto を許すベース(上の auto の運用担当者のプロファイルのバージョンなど)の上に新しいワークスペースプロファイルを作る。すでに動いているセッションは元のモードのまま動く。push 承認はモードとは別である。auto モードでも、push 承認がオンか、付けたリポジトリの push ポリシーが ask なら、どのリポジトリへの push でも、push のたびに人に尋ねる。エージェントの GitHub タブを初めて保存するときは push 承認がオフの状態から始まるが、GitHub 設定のない release(この設定より前に作った release など)はオンとして読む。承認なしで自動 push するには、GitHub タブで push 前の人の承認 がオフになっていることを確かめて保存する。オフにしても、承認なしで進むのは、付けたリポジトリの push ポリシー(allow・ask・deny)も allow のときだけである。ポリシーが deny なら push 自体がブロックされ、それ以外では、どのリポジトリへの push も、このスイッチとそのポリシーのうち厳しいほうに従う。人の承認を受けるには、スイッチをオンにするか、ポリシーを ask にする。

承認: 人だけが行う見出しのリンクをコピー

権限リクエストと質問に答えるには sessions:approve scope が必要である。worker 内のエージェントが持つ認証情報は /v1 で 401 になるため、自分で承認することはできない。エージェントキーも sessions:approve を持てるが、そのキーで開始したセッションのリクエストは承認できない。答え方は 承認待ちと再開 にある。

セッションを見られるからといって、そのセッションのリクエストに答えられるわけではない。権限リクエストと質問に答え、push・PR を承認するのは次の人だけである。

• セッションを作った人(API キーが作ったセッションならそのキー)
• そのセッションのエージェントの管理者
• ワークスペースの owner・admin

共有でセッションを見ているだけの人が答えると 403 FORBIDDEN(reason_code: role)になり、リクエストは開いたまま残ってセッションは needs_input のままである。見られないセッションはこれまでどおり 404 である。GET /v1/sessions/{id}/pending-requests の answerable が、呼び出した人が答えられるかを示す。コンソールは false のとき、許可・拒否を理由とともに無効にして表示する。

エージェント管理者見出しのリンクをコピー

エージェントを作成した人が、そのエージェントの管理者になる。管理者は member であっても、そのエージェントのカード修正、リリース、有効化、認証情報の紐付け、管理者の指定、エージェントキーの発行を行える。人やチームを管理者として追加でき、チームの場合はそのチームのメンバー全員が管理者になる。チームを新しく追加できるのは、チームを管理する owner・admin だけである。member のエージェント管理者はチームを追加できないが、追加済みのチームを外すことと、人の追加・削除はできる。

エージェントには常に担当チームが一つあり、変えることはできても空にはできない。担当チームのチーム管理者(lead)はそのエージェントの管理者で、メンバー(member)は管理しない。owner・admin でなければ、自分が所属するチームだけを担当チームに選べる。担当チームに決まったチームは、そのエージェントをアーカイブするか担当チームを移すまで削除できない。

チームのロールはコンソールのチーム画面で見る。メンバー表の チームのロール 列が チーム管理者(lead)と メンバー(member)を分け、所属チーム の一覧にも自分のロールが付く。owner・admin はメンバーの行の ロールを変更 でロールを選んで 保存 する(PATCH /v1/teams/{team_id}/members/{user_id} {"role"})。担当チームになっているチームを削除しようとすると、コンソールは削除せず、そのチームが担当チームのエージェントの名前とリンクを示す(409 TEAM_MANAGES_AGENTS)。先に各エージェントの担当チームを変える。

エージェントを見られる範囲は次のとおり。

エージェントの外の member ができること見出しのリンクをコピー

owner・admin、エージェント管理者、担当チームのメンバーをそのエージェントの内側と呼び、それ以外の member を外側と呼ぶ。外側の member がエージェントで何をできるかは、ワークスペースの設定二つが決める。変えられるのは owner・admin だけで(PATCH /v1/workspaces/{id}/agent-access)、変えるたびに receipt が残る。今の値は GET /v1/auth/me の workspace.settings にある。

• agent_outsider_access と agent_outsider_session_visibility はすべてのエージェントに適用される。エージェントには常に担当チームがある。担当チームが必須になる前にチームがなかったエージェントは、メンバーのいない保管チーム(名前を変えても、サーバーは保管チームとして認識する)が引き受けた。これらのエージェントの workspace セッションは、適切なチームに移すまで以前と同じくすべてのメンバーに見える。
• 外側の member でも、自分が開始したセッションと、自分や自分のチームを指定して共有された(people・team)セッションは引き続き見える。
• どちらの設定も次のリクエストから、作成済みのセッションにも適用される。開いているイベントストリームは次の確認で切れる。担当チームを変えたときや、メンバーがチームから外れたときも同じである。
• 使用量の合計(セッション数・費用・成果数)は変わらず、最近の成果一覧から見られないセッションの行だけが抜ける。
• 共有範囲が workspace でも外側の member に見えないセッションは、GET /v1/sessions/{id}/share の audience_limited が true になる。

curl -sS -X PATCH "$API/v1/workspaces/$WID/agent-access" "${WEB[@]}" \
  -d '{"agent_outsider_access": "view"}' | jq -c '{agent_outsider_access, agent_outsider_session_visibility, changed: (.receipt_id != null)}'

{"agent_outsider_access":"view","agent_outsider_session_visibility":"managing_team","changed":true}

WID は GET /v1/auth/me の workspace.id である。

コンソールでは ワークスペース設定 の エージェントへのアクセス で変える。担当チーム外のメンバーのエージェントへのアクセス は 表示と実行(use)・表示のみ(view)・非表示(none)、ワークスペース公開のセッション は 担当チーム内のみ(managing_team)・すべてのメンバー(workspace)である。変えた値だけを送り、保存すると画面が GET /v1/auth/me を読み直す。owner・admin でないメンバーには、選択肢なしで今の値だけが表示される。

作成の AID と WEB を引き続き使う。

curl -sS "$API/v1/agents/$AID/admins" "${WEB[@]}" | jq '{users: [.users[].email], teams}'

{
  "users": [
    "owner@example.test"
  ],
  "teams": []
}

認証情報の紐付け見出しのリンクをコピー

カードには、使う認証情報の名前だけを capabilities.credential_refs に書く。値は Werft の外 (secret store、remote MCP server の接続) にある。その名前をこのエージェントが使ってよいという紐付けは、管理者が別途作成する。カードに書かれた名前のうち紐付けられていないものがあると、有効化は 409 CREDENTIAL_UNBOUND になる。

curl -sS "$API/v1/agents/$AID/credential-bindings" "${WEB[@]}" -d '{"credential_ref": "notion-token"}' \
  | jq '{credential_ref: .binding.credential_ref, created}'
curl -sS "$API/v1/agents/$AID/credential-bindings" "${WEB[@]}" | jq -c '[.items[].credential_ref]'

{
  "credential_ref": "notion-token",
  "created": true
}
["notion-token"]

解除 (DELETE /v1/agents/{id}/credential-bindings/{binding_id}) は、動作中のセッションを止めない。次のセッションから遮断される。すぐに遮断するには、外部サービスでその認証情報を失効させる。

次のステップ見出しのリンクをコピー

• 承認待ちと再開: 権限リクエストに答える
• API キー: 個人キーとエージェントキー