エージェント、モデル、権限モードを選ぶ

ワークフローの各タスクをどのエージェントに任せるか、どのモデルを使うか、実行中に許可なしで操作できるかどうかは、それぞれタスクの agent、model と effort、mode の各フィールドで決まります。なかでも、時間をかけて検討する価値があるのは mode です。タスクエージェントは、いったん止まって許可を求めると、誰かが応答するまで待ち続けます。そのため mode は、誰も見ていない間にワークフローを最後まで実行できるかどうかを決め、同時に、そのためにどれだけのリスクを引き受けるかも決めます。

エージェントを選ぶ

agent に claude と書くと Claude Code が、codex と書くと Codex がタスクを実行します。書かない場合、タスクはプロジェクトのデフォルトのエージェントに任されます。デフォルトのエージェントは cdg init のときに決まり、後から変えるには、プロジェクト設定の defaultAgent を変更します。一方に実装を、もう一方にレビューを任せるなど、1 つのワークフローの中で両者に作業を分担させる方法は、Claude Code と Codex を組み合わせるを参照してください。

mode を書いたタスクには、agent も明記しておくことをおすすめします。mode の書き方は 2 つのエージェントで異なり、検証では、タスクが実際に使うエージェントに合わせてチェックされます。デフォルトのエージェントは通常、マシンごとのローカル設定に記録されています。そのため、同じワークフローファイルをデフォルトのエージェントが異なるマシンに持っていくと、agent を書いていないタスクはもう一方のエージェントで実行されることになり、元のエージェント向けに書いた mode は、たいてい検証に通らなくなります。

プロジェクト設定に availableAgents を書いている場合、タスクで使えるのは、そこに挙げたエージェントだけです。リストにないエージェントを使うと、検証でエラーになり、このフィールドがどのファイルにあるかが示されます。

モデルと推論エフォートを選ぶ

model はモデルを、effort は推論エフォートを指定します。CodeDAG は、どちらもそのままエージェントに渡します。書かない場合、タスクは、エージェント側で設定されているデフォルトのモデルと推論エフォートを使います。ほとんどのタスクでは、書かなくてもかまいません。コストや品質を調整したい場合は、機械的なタスクにはコストの低い設定を使い、高性能なモデルと高めの推論エフォートは、レビューやまとめのように判断が必要なタスクに回すのが一般的です。コスト面の考え方は、タスクごとにモデルを選ぶを参照してください。

2 つのフィールドは、model: opus、effort: high のように、タスクの下に直接書きます。指定できる値は、エージェントごとに決まっています。

• Claude Code： model には、エイリアスの sonnet、opus、haiku を書けます。それぞれ Sonnet、Opus、Haiku シリーズのモデルを指します。完全なモデル名を書くこともできます。
• Codex： model には、gpt-6.1-sol のようなモデル名を書きます。現在使えるモデルは、Codex の /model メニューで確認してください。
• 推論エフォート： effort でどのレベルを使えるかは、モデルによって異なります。最も一般的なのは low、medium、high で、それより高い xhigh や max などのレベルは、一部のモデルしか対応していません。

CodeDAG は、この 2 つのフィールドの値をチェックしません。名前を書き間違えても検証には通り、タスクの実行時になって初めて、エージェントがエラーを出します。モデルとレベルは、エージェントの更新に伴って変わります。最新の情報は、Claude Code のモデル設定のドキュメントと、Codex のモデルのドキュメントを参照してください。Claude Code のタスクでモデルを選ぶときには、もう 1 つ注意点があります。auto 権限モードは、一部のモデルでしか使えません。Claude Code での書き方を参照してください。

無人実行か有人実行かを決める

mode は、タスクエージェントが実行中にどの操作をそのまま実行でき、どの操作でいったん止まって許可を待つかを決めます。つまり、誰も見ていない間にワークフローを最後まで実行できるかどうかも、mode で決まります。タスクエージェントは、いったん許可を求めると、誰かがそのセッションに入って応答するまで待ち続け、その間もタスクの状態は working と表示されたままです。この状況に気づく方法は、止まったままかどうかを見分けるにはを参照してください。無人実行にしたい場合は、フルアクセスを選ぶか、許可の判断をエージェント側の自動レビューに任せます。自分で許可リクエストに応答するレベルは、そばにいるときにしか向いていません。3 つのレベルは、2 つのエージェントでそれぞれ次のように書きます。

フルアクセスでは、席を外している間もワークフローを最後まで実行できます。2 つ目のワークフローのチュートリアルで使っているのが、このレベルです。向いているのは、信頼できるタスクです。つまり、プロンプトを自分で書いていて、タスクが読む資料の出どころが信頼でき、このマシンに、エージェントに触れさせたくないものがない場合です。その代わり、エージェントの操作は権限チェックを通らなくなります。それによって何が起こりうるかは、下の注意書きを参照してください。

中程度のアクセスでは、操作に制限がかかります。Claude Code は、分類器が安全と判断した操作だけを通します。Codex は、コマンドをサンドボックスの中で実行し、書き込みはタスクのワークスペースにしか認めません。このレベルは、共有データベース、リモートリポジトリ、本番環境の認証情報のように、エージェントに自由に操作させたくないものにタスクが触れる場合に向いています。まだよく知らないワークフローを初めて実行する場合にも向いています。ブロックされた操作は、許可を得なければ先へ進めません。そして、その許可を誰が判断するかによって、このレベルで無人実行ができるかどうかが決まります。

許可を自動レビューに任せる場合、タスクは人を待って止まることがありません。Codex の approve-for-me は、すべての許可リクエストを Codex 自身の自動レビューに回し、通すか拒否するかは自動レビューが決めます。Claude Code の auto も、分類器がバックグラウンドで判断しますが、まれに止まってユーザーに許可を求めることがあるため、誰かが様子を見ている必要があります。クイックスタートで使っているのが、このレベルです。

許可を自分で出す場合は、リクエストが 1 回あるたびにタスクが止まり、そのタスクに依存する下流も、キューの後ろに並んだワークフローも一緒に待つことになります。そのため、そばにいるときや、定期的に確認できるときにしか向いておらず、夜通しの実行には向きません。応答の方法は、許可リクエストに応答するを参照してください。エージェントにオーケストレーションを任せている場合は、あらかじめ取り決めた範囲内で、オーケストレーションエージェントに代わりに応答させることもできます。投入前にエージェントと確認しておく 3 つのことを参照してください。

mode はタスクごとに設定するため、同じワークフローの中で、タスクによってアクセスレベルを変えられます。ただし、許可待ちで止まる可能性のあるタスクが 1 つでもあれば、ワークフロー全体について、誰かが様子を見ている必要があります。

mode を書かない場合

mode を書かない場合、CodeDAG はエージェントに権限設定を何も渡さず、タスクエージェントは自身の設定に従って起動します。たとえば、Claude Code の設定ファイルにある permissions.defaultMode や、Codex の ~/.codex/config.toml です。いずれも設定されていなければ、エージェントの組み込みのデフォルトが使われます。こうした設定はワークフローファイルからは読み取れず、エージェントの組み込みのデフォルトも、バージョンによって変わります。そのため、同じワークフローでも、マシンを変えたりエージェントをアップグレードしたりすると、最後まで止まらずに実行できていたものが、頻繁に止まるようになることがあります。すべてのタスクに mode を明記しておけば、各タスクのアクセスレベルがファイルそのものからわかり、マシンごとの設定にも左右されなくなります。

mode が適用されるセッション

mode は、投入時にワークフローの定義と一緒に確定し、そのタスクが今回の実行で起動するセッションは、すべてこの mode で動作します。レビューのときに request-changes で修正を続けさせる場合も、rework でやり直させる場合も、同じ mode が引き継がれます。タスクの実行が終わった後に cdg task view でそのセッションに入り直した場合も、そこで依頼した作業は、このアクセスレベルで実行されます。

分離ブランチモードには、タスクの mode で動作しないセッションが 1 種類あります。自動マージでコンフリクトが発生したときに、CodeDAG がその解決のために起動するエージェントセッションです。このセッションには許可リクエストに応答する手段がないため、常にフルアクセス（yolo）で動作し、誰も見ていなくてもマージを終えられます。タスクに、ユーザーの許可を必要とする mode を書いていても同じです。コンフリクト解決のセッションに別のアクセスレベルを使わせたい場合や、コンフリクトを解決するエージェントを固定したい場合は、ワークフローに mergeConflictAgent を書きます。

無人実行でもゲートは置ける

フルアクセスで省かれるのは、タスクの実行中に操作を 1 つずつ許可する手順だけです。結果の確認は、ワークフローそのものに組み込めます。重要なノードのレビューゲートを閉じる、検証タスクを置く、コードは変更せずレビューだけをするタスクを置く、といった方法です。次のワークフローは、席を外している間に実行するのに向いています。3 つのタスクはすべてフルアクセスで、結果を確認する箇所を最後に置いています。

tasks:
  - id: 1
    title: ユニットテストを追加
    agent: claude
    mode: bypassPermissions
    prompt: |
      リポジトリの中から、ユニットテストのない関数を 3 つ見つけ、ユニットテストを追加して、通るまで実行してください。
      どのテストを追加したか、それぞれどのファイルにあるかを、docs/notes/new-tests.md に書いてください。
      追加または変更するのは、テストファイルとこの記録だけにしてください。

  - id: 2
    title: 追加したテストをレビュー
    dependencies: [1]
    agent: claude
    mode: bypassPermissions
    model: opus                # レビューには判断が必要なので、高性能なモデルを使う
    effort: high
    prompt: |
      docs/notes/new-tests.md と、そこに挙げられているテストファイルを読み、
      これらのテストが関数の動作を本当に検証しているか、抜けているエッジケースがないかを確認して、
      見つかった問題を 1 件ずつ docs/notes/test-review.md に書いてください。コードとテストは一切変更しないでください。

  - id: 3
    title: 問題を修正して全テストを実行
    dependencies: [2]
    agent: claude
    mode: bypassPermissions
    autoAccepted: none         # 完了したら止まり、結果の確認を待つ
    prompt: |
      docs/notes/test-review.md を読み、指摘されている問題を 1 件ずつ修正してください。
      その後、プロジェクトのすべてのテストを実行し、失敗したテストを修正して、すべて通るようにしてください。
      どのチェックを実行したか、何を変更したか、まだ通っていないものは何かを、docs/notes/test-report.md に書いてください。

タスク 2 はコードを読んで問題をファイルに書くだけで、修正はタスク 3 が行います。タスク 3 は検証タスクで、すべてのテストを実行し、結果をレポートにまとめます。このタスクには autoAccepted: none を設定しているので、完了後に止まってレビューを待ちます。docs/notes/test-report.md を読んでから、承認するか、修正を続けさせるかを決めてください。検証タスクがあってもこのゲートを残すのは、CodeDAG がテスト結果を読まないからです。テストを直しきれなかった場合でも検証タスクは done になり、ゲートが開いていれば自動承認されてしまいます。検証タスクを参照してください。同じように設定する価値のあるほかのノードは、ゲートを閉じる価値があるノードを参照してください。

Codex で実行する場合は、agent を codex に、mode を yolo に変え、model と effort は削除するか、Codex 用の値に置き換えます。

ゲートが制御するのは、結果を下流に渡してよいかどうかであり、タスクの実行中にエージェントがどんなコマンドを実行したかには及びません。フルアクセスのリスクは、引き続き、信頼できるタスクと、自分で管理できる環境によって抑える必要があります。

エージェントを初めて起動する前の確認

エージェントには、初回にだけ表示される確認画面がいくつかあります。そのうち自分で応答する必要があるのは 2 つで、どちらも Claude Code の画面です。フルアクセスの警告と、作業ディレクトリ外のファイルの読み取りについての確認です。この 2 つは、エージェントにどこまでの権限を与えるかを決めるもので、このコンピューターについてユーザー自身が与える許可にあたります。そのため CodeDAG が代わりに応答することはなく、タスクがバックグラウンドでこの画面に行き当たると、止まって応答を待ちます。どちらも、投入する前にターミナルで済ませておけば、以降このコンピューターでは表示されません。ディレクトリと、その中のルールファイルを信頼できるかどうかを確認する画面には、CodeDAG が代わりに応答します。

Claude Code のフルアクセスの警告にあらかじめ同意する

Claude Code のタスクをフルアクセスのモード bypassPermissions（エイリアスの yolo を含みます）で実行する場合で、このコンピューターでまだこのモードの警告に同意したことがないときは、投入する前にターミナルで一度済ませておきます。claude --permission-mode bypassPermissions を実行し、「Yes, I accept」を選んで終了してください。一度同意すれば、このコンピューターでは、どのディレクトリでも表示されなくなります。この警告は、権限チェックをスキップした結果を引き受けることについて、ユーザーの確認を求めるものです。そのため、CodeDAG が代わりに確認することはありません。Codex をフルアクセスで実行する場合、この手順はありません。

あらかじめ同意していなくても、後から対応できます。その場合、タスクは on-hold で止まり、理由は agent-bypass-permissions-unaccepted になります。cdg task status <タスク ID> -w <ワークフロー> の診断に、ターミナルで警告に同意する方法が示されます。そのとおりに済ませてから cdg task recover <タスク ID> -w <ワークフロー> を実行すると、タスクは最初から起動し直されます。

Claude Code に作業ディレクトリ外のファイルの読み取りをあらかじめ許可する

Claude Code のタスクを auto モードで実行し、リポジトリ外のファイルも読ませる場合で、「Allow this read outside the working directories?」という確認にまだ答えたことがないときは、投入する前にターミナルで一度答えておきます。この確認は、起動時ではなく、タスクの実行途中で、Claude Code が初めて作業ディレクトリ外のファイルを読もうとしたときに表示されます。これについても、CodeDAG が代わりに選択することはありません。

1. リポジトリのルートで claude --permission-mode auto を実行し、次のプロンプトを送信します。パスは、リポジトリ外にあるほかのファイルに置き換えてもかまいません。

   Read ツールを使って、~/.claude/projects/ にある最近変更された .jsonl ファイルを 1 つ選び、その先頭 10 行を読んでください。

2. 「Allow this read outside the working directories?」と表示されたら、「Yes, and keep allowing any reads outside the working directories」を選びます。この選択は、このコンピューターのすべてのプロジェクトに適用され、以降は尋ねられません。確認が表示されなかった場合は、以前にすでに許可しています。

3. Claude Code を終了します。

あらかじめ許可していなくても、後から対応できます。その場合、タスクはこの確認で止まって応答を待ちます。タスクのセッションに入って選択すれば、タスクはそのまま実行を続けます。方法はエージェントが許可または回答を待っているを参照してください。

CodeDAG が代わりに応答する確認

ディレクトリの信頼。 どちらのエージェントも、あるディレクトリで初めて起動するときに、そのディレクトリを信頼するかどうかを尋ねます。タスクは、ユーザー自身が登録したワークスペースで実行されるため、CodeDAG がユーザーに代わって、信頼するほうを選びます。別のリポジトリに移った場合や、並列実行のためにレプリカのディレクトリを新しく作った場合も同じです。この選択は、エージェント自身が記録します。Claude Code はディレクトリ単位で、Codex は Git リポジトリのルート単位で自身の config.toml に記録します。

外部 CLAUDE.md のインポート。 プロジェクトまたはその上位ディレクトリにある CLAUDE.md が、@ を使って作業ディレクトリ外のファイルをインポートしている場合、Claude Code は初回の起動時に「Allow external CLAUDE.md file imports?」と尋ねます。インポートされるのは、ユーザー自身がこのプロジェクトやこのコンピューターのために設定したルールファイルです。そのため、CodeDAG がユーザーに代わって、インポートを許可するほうを選びます。この選択も、ディレクトリの信頼と同じく、起動したディレクトリ単位で記録されます。新しいリポジトリでも、並列実行のために新しく作ったレプリカのディレクトリでも、CodeDAG がタスクの起動時に応答します。

Claude Code での書き方

Claude Code のタスクの mode には、権限モードの名前を 1 つ書きます。CodeDAG は、それを --permission-mode として Claude Code に渡します。無人実行では bypassPermissions と書きます。CodeDAG が用意しているエイリアスの yolo でもかまいません。有人実行では auto と書き、タスクで使うモデルが auto モードに対応していない場合は、代わりに acceptEdits と書きます。

tasks:
  - id: 1
    title: lintの問題を修正
    agent: claude
    mode: auto      # 有人実行。無人実行にする場合は bypassPermissions に変える
    model: sonnet   # auto は、対応しているモデルでしか使えない
    prompt: |
      プロジェクトの lint コマンドを実行し、報告された問題をすべて修正して、lint が通るようにしてください。
      変更するのは、lint が報告したファイルだけにしてください。

auto モードには、使うための条件があります。まず、タスクで使うモデルが対応している必要があります。ここでいうモデルとは、タスクの model のことで、書いていない場合は Claude Code のデフォルトモデルです。Haiku 4.5 のような古いモデルは対応していません。また、組織の管理者が auto モードを無効にしていることもあります。条件を満たさない場合、Claude Code は Manual モード（default）で起動し、タスクは、許可が必要な最初の編集またはコマンドで止まります。auto と書いたのに、タスクが許可待ちで止まるを参照してください。代わりに acceptEdits を使うと、ファイルの編集と、mkdir、mv、cp のようなよく使うファイル操作のコマンドはそのまま実行されますが、テストの実行やビルドなど、それ以外のコマンドにはすべて許可が必要になり、タスクが止まる回数はずっと多くなります。そのほかのモード名とエイリアスは、権限モードの構文を参照してください。

bypassPermissions と auto の 2 つのモードには、初回にだけ表示され、自分で応答する必要のある画面が 1 つずつあります。bypassPermissions の起動時に表示されるフルアクセスの警告と、auto モードのタスクが初めて作業ディレクトリ外のファイルを読むときに表示される確認です。まだ応答したことがなければ、タスクはそこで止まって応答を待つので、投入する前にターミナルで済ませておきます。

bypassPermissions を使っていても、Claude Code は一部の操作については止まってユーザーに尋ねます。たとえば、権限ルールで確認が必要と設定されているツール、エージェントが自分からユーザーに投げかける質問、ルートディレクトリやホームディレクトリのような重要なパスを削除するコマンドです。この場合も、タスクはそこで止まります。

モード名と各モードの具体的な動作は Claude Code が決めており、バージョンによって変わることもあります。正確な情報は、claude --help と公式の権限モードのドキュメントで確認してください。

Codex での書き方

Codex のタスクの mode は、2 通りの書き方のどちらかで書きます。全体を 1 つの省略形にするか、カンマで区切った複数の キー=値 にするかです。省略形は 2 つあります。yolo はフルアクセス、approve-for-me（auto と書いてもかまいません）は自動レビューのレベルです。自分で許可リクエストに応答する場合は、ask-for-approval=on-request,sandbox=workspace-write,network_access=true と書きます。こうすると、Codex はサンドボックスの中では自由に作業し、サンドボックスの外に出る必要があるときにだけ、ユーザーに許可を求めます。

tasks:
  - id: 1
    title: lintの問題を修正
    agent: codex
    # 許可は自分で出す：サンドボックス内の操作はそのまま実行し、外に出る必要があるときに許可を求める
    # 無人実行にする場合は、approve-for-me（自動レビュー）または yolo（フルアクセス）に変える
    mode: "ask-for-approval=on-request,sandbox=workspace-write,network_access=true"
    prompt: |
      プロジェクトの依存関係をインストールし、プロジェクトの lint コマンドを実行して、報告された問題をすべて修正し、lint が通るようにしてください。
      変更するのは、lint が報告したファイルだけにしてください。

yolo を指定すると、Codex は許可を求めず、サンドボックスも使わず、リアルタイムの Web 検索を有効にします。Codex 自身の --dangerously-bypass-approvals-and-sandbox に --search を加えたものに相当します。

approve-for-me を指定すると、Codex は workspace-write サンドボックスの中で作業し、サンドボックスの外に出る必要があるときは、通常どおり許可リクエストを出します。ただし、各リクエストは Codex 自身の自動レビューが判断し、人を待って止まることはないため、このレベルでも無人実行ができます。拒否された操作は実行されません。エージェントは拒否を受けて自分でやり方を調整し、別の方法で作業を続けます。この省略形は、それだけを mode の値として書く必要があり、sandbox や search などのキーと組み合わせることはできません。

同じターンの中で自動レビューに何度か続けて拒否されると、Codex はそのターンを中断し、タスクは on-hold で止まります。理由は agent-lifecycle-state-unavailable です。cdg task status <タスク ID> -w <ワークフロー> の診断には、Codex が示した中断の説明が含まれています。そこに書かれた原因に対処してから、cdg task recover <タスク ID> -w <ワークフロー> でタスクを続行させます。エージェントセッションの問題を参照してください。

キーと値で書く場合、ask-for-approval はいつ許可を求めるかを、sandbox はコマンドがどの場所を読み書きできるかを、approvals_reviewer は許可リクエストを誰が判断するかを決めます。すべてのキーと値は、権限モードの構文を参照してください。範囲外の値を書くと、cdg dag validate がエラーを出すため、タスクの起動時になって初めて失敗するということはありません。

キーと値で書いて approvals_reviewer を省略した場合、許可リクエストを誰が判断するかは、各コンピューターの ~/.codex/config.toml の設定で決まります。そのため、同じワークフローが、あるコンピューターでは自動レビューに回され、別のコンピューターでは人を待って止まることがあります。mode を approve-for-me にするか、キーと値の書き方で approvals_reviewer を明記すれば（user はユーザー本人に、auto_review は自動レビューに任せます）、どのコンピューターでも同じ動作になります。

操作を通すかどうかを自動レビューに任せたくはないが、無人実行にはしたいという場合は、ask-for-approval を never に設定できます。たとえば ask-for-approval=never,sandbox=workspace-write,network_access=true と書きます。サンドボックスが許す操作はそのまま実行され、許さない操作はその場で失敗し、タスクが人を待って止まることはありません。その代わり、ブロックされた操作を後から許可する人はいないため、タスクは作業をやり残したまま終わる可能性があります。検証タスクかレビューゲートを組み合わせておくことをおすすめします。

よくある質問

タスクが許可待ちで止まった場合は、どうすればよいですか

cdg task view <タスク ID> -w <ワークフロー> でタスクエージェントのセッションに入り、エージェント本来の画面で選択してから、Ctrl+C で抜けます。タスクはそのまま実行を続けます。タスクが許可待ちになっていることを確かめる方法は、止まったままかどうかを見分けるにはを参照してください。今回の実行の mode はすでに確定しているため、この後に出る許可リクエストにも、1 つずつ応答する必要があります。今後は止まらないようにしたい場合は、ワークフローファイルの mode を変更します。変更は、次回の投入から有効になります。

auto と書いたのに、タスクが許可待ちで止まる

多くの場合、このタスクでは auto モードが使えず、Claude Code が Manual モードにフォールバックしています。最もよくある原因は、model に Haiku 4.5 のような古いモデルを書いている場合のように、タスクで使うモデルが auto に対応していないことです。組織の管理者が auto モードを無効にしている場合や、auto モードが一時的に使えない場合も、同じようになります。このとき、タスクのログには、auto mode unavailable for this model や ⏸ manual mode on のような、Claude Code のステータスバーの表示が出ています。auto が使える場合でも、分類器が何度も続けて操作をブロックすると、Claude Code は一時的に、操作を 1 つずつ確認する動作に戻ります。

すでに止まっているタスクには、セッションに入って応答すれば足ります。今後のワークフローでは、このタスクのモデルを、sonnet や opus のような auto 対応のものに変えます。acceptEdits に変える方法もありますが、より多くのコマンドで止まるようになります。フルアクセスのリスクを受け入れられる場合は、bypassPermissions に変えます。

2 つのエージェントの利用上限は別々ですか

別々です。一方が上限に達しても、もう一方のタスクはそのまま実行を続けます。CodeDAG クレジットは、どのエージェントやモデルを選んでも変わらず、1 タスクにつき 1 クレジットです。この点を生かして 2 つのエージェントにタスクを振り分ける方法は、2 つのエージェントの利用上限は互いに影響しないを参照してください。

関連ページ

• 介入と制御：タスクが許可待ちで止まったときに、セッションに入って応答したり、方向を修正したりします。
• Claude Code と Codex を組み合わせる：1 つのワークフローの中で、2 つのエージェントに作業を分担させたり、互いにレビューさせたりします。
• ワークフローファイルリファレンス：agent、mode、model、effort のすべての値とデフォルト値。