Codex CLIからosFoundryのセッションに仕事を渡す前の確認ポイントまとめ

この記事でやること

• Codex CLIからosFoundryのエージェント・チーム・ループのセッションに仕事を渡すとき、どの席とスコープを選べばいいかを整理します
• 引き継ぎの提案(propose_session_handoff)とrunの依頼(request_session_run)の使い分けを、表で確認します
• 呼び出しが通らないときに、どこを順に見ればいいかをまとめます

前提・環境

• Codex CLIからosFoundryのMCPサーバー(https://api.osfoundry.io/api/v1/external-mcp)に接続済み。接続の作り方は省略します
• 渡し先のセッションは、接続を追加したプロジェクトの中にある
• 記事中のセッション名、ID、文面は表示例です
• Codexのツール名は、MCPのツール名に mcp__osfoundry__ が付いた形で見えます

使うツールは7つ

ツール	何をするか	スコープ	読み取り専用
propose_session_handoff	オーナーに引き継ぎを提案する。承認されるまでrunは始まらない	osfoundry:write	いいえ
cancel_session_handoff	自分が出した提案を、承認前に取り下げる	osfoundry:write	いいえ
request_session_run	Runner席のセッションに、上限付きのゴールをキューに入れる	osfoundry:run	いいえ
read_session_state	セッションの状態と直近のタスクを読む	osfoundry:read	はい
read_session_task_result	この接続が始めたタスクの状態と結果を読む	osfoundry:read	はい
read_session_mail	この接続宛てのノートと、自分が投稿したノートを読む	osfoundry:read	はい
post_session_note	セッションに名前付きのノートを投稿する。runは起きない	osfoundry:write	いいえ

~/.codex/config.toml で default_tools_approval_mode = "writes" にしておくと、読み取り専用でない4つの前でだけCodexが確認を出します。

席とスコープの組み合わせ

席はConnectedタブの「Agent, Team, and Loop sessions」で、セッションごとに選びます。スコープはCodexの config.toml の scopes と、サインイン時の「Requested capabilities」で決まります。両方そろって初めて呼べます。

やりたいこと	席	必要なスコープ
状態と結果を見るだけ	Viewer(Observer)	osfoundry:read
ノートを書く、引き継ぎを提案する	Contributor	osfoundry:read, osfoundry:write
承認なしでrunを始める	Runner	上記に加えて osfoundry:run

~/.codex/config.toml

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write"]
default_tools_approval_mode = "writes"

上はContributor向けの例です。osfoundry:run を入れていないので、仮にRunner席を与えてもrunは始められません。提案だけさせたいときの安全側の設定です。

提案とrun、どちらを使うか

観点	propose_session_handoff	request_session_run
誰が承認するか	オーナーがその都度「Accept and run」	Runner席を与えた時点で承認済み
必須項目	goal, context_summary, requested_output など6つ	goal など4つ
goalの上限	5,000文字	10,000文字
ほかの上限	context_summary 5,000文字、requested_output 1,000文字	なし
max_rounds	1〜10(省略可)	1〜10(省略可)
取り消し	承認前なら cancel_session_handoff	取り消すツールはない

迷ったら提案にしておくのが無難です。オーナーは「Outside assistant requests」でゴールと要約を読んでから決められます。毎回同じ種類の仕事を頼むループなど、オーナーがもう中身を分かっている相手にだけRunnerを使う、という分け方がしっくりきます。

max_rounds の既定値はスキーマに書かれていません。回数を気にするなら明示して送ってください。オーナーには「Up to N rounds on your agent runtime」として表示されます。

提案を書くときのコツ

オーナーが読んで判断する文面なので、Codexへの指示文ではなく、人への依頼文として書かせます。

propose_session_handoff.json

{
  "session_type": "loop_session",
  "session_id": "…",
  "goal": "今週分のリリースノート下書きを作る",
  "context_summary": "mainに入った変更は3件。PR #212 CSVエクスポートの1万行上限を撤廃、PR #215 請求書PDFのフォント修正、PR #218 ログ出力の整理(ユーザー影響なし)。",
  "requested_output": "ユーザー向けの箇条書き3点以内。#218は載せない。",
  "max_rounds": 3,
  "idempotency_key": "codex-relnote-2026w45"
}

• context_summary には、セッション側が知らないことだけを書く。リポジトリの中身はセッションから見えません
• requested_output は形と量を決めておく。返ってきたものを read_session_task_result で読むとき、確認がしやすくなります
• idempotency_key は「何を頼んだか」が分かる値にする。リトライしても同じ提案が二重にできません

渡したあとの確認

1. read_session_state で、状態と直近のタスクを見る。osFoundry側の画面では、外部からの依頼のきっかけは「Requested by an outside assistant」と表示されます
2. read_session_task_result で、自分が始めたタスクの結果を読む。他の接続のタスクは読めません
3. 補足があれば post_session_note で返す。runは起きないので、追加作業が要るなら改めて提案します
4. 返事は read_session_mail で読む。1回20件までで、古いものは before_id で辿ります。セッション内部のエージェントの分析は含まれません

呼び出しが通らないときに見るところ

上から順に確認すると早いです。

1. スキーマで弾かれていないか

サーバーは入力をスキーマで検証します。よくあるのは次の4つです。

• 引き継ぎの goal が5,000文字を超えている。runなら通る長さでも、提案では長すぎます
• context_summary か requested_output がない
• max_rounds が0か11以上
• model など、スキーマにない欄を足している。additionalProperties: false なので弾かれます。セッションのモデルは呼び出し側からは選べません

2. 席が足りているか

Connectedタブで、その接続の席を確認します。Viewerでは書き込み系は呼べません。runの依頼はRunnerだけです。

3. スコープが足りているか

config.toml の scopes を変えたら、codex mcp login osfoundry でサインインし直します。サインイン画面の「Requested capabilities」に「Run sessions where you grant a runner role」が出ていなければ、osfoundry:run は入っていません。

4. オーナーの判断待ちではないか

提案は、オーナーが押すまで pending のままです。オーナーには「Codex CLI requests a handoff」の通知が出ています。Declineされた提案は戻りません。必要なら文面を直して出し直します。

5. ローカルにしかないものを渡そうとしていないか

サーバーの initialize の返事は「Local-only data is unavailable to cloud clients.」です。デスクトップのローカルフォルダや未同期のアイテムは、セッション側からも見えない前提で文面を書きます。

まとめ

• 席(Viewer / Contributor / Runner)とスコープ(read / write / run)の両方がそろって、初めてツールが呼べる
• 人に判断してほしいなら propose_session_handoff、事前に任されているなら request_session_run
• 提案は人が読む文面として書き、context_summary にはセッションが知らないことだけを入れる
• 結果はこの接続が始めたタスクの分だけ返り、セッション内部の分析は返らない

セッションの中で何が見えるかはエージェントセッションのページ、引き継ぎの全体像はハンドオフのページにまとまっています。