「このAIモデルは定額内か従量課金か」を推測せず実測で確定し、ルールを機械で二段構えにする

AI コーディングエージェントを組織で使うと、必ず「このモデルは定額プランに含まれるのか、それとも 追加課金なのか」という問いが出る。ここを推測で決めると高確率で間違える。実際に「別課金だから 全面禁止」という社内ルールを敷いたが、後で実測したら課金ゼロだったという事例がある。 逆に「専用のバーが出ているから定額内だろう」と判断したら従量だった、という逆側の間違いも起こる。

この指示書は、①課金区分を実測で確定させる手順と、②確定した結果を機械が強制する形に落とす型を扱う。 特定のベンダーに依存しない考え方だが、コンソールの画面名は主要な AI コーディングエージェントの 管理画面を想定して書いている。

1. なぜ推測が外れるのか（2つの罠）

罠1: 専用のレート制限バーがあることは「定額内」の証明にならない。 高速モードのような「追加課金される機能」でも、専用のレート制限プールを持つことがある。 管理画面に「◯◯ limit」という独立したバーが出ていても、それは 「このモデル専用の上限がある」という意味でしかなく、その消費が無料かどうかは何も語っていない。

罠2: 上限に達していないから課金されていない、とは言えない。 多くのサービスのドキュメントには「この機能はプランに残枠があっても追加クレジットから引かれる」 と明記されている。つまり上限とは無関係に課金される機能が存在する。 逆にこれが判定の鍵になる（後述）。

2. 確定手順（これだけが証拠になる）

2-1. 支出レポートを出す

管理コンソールの分析／Analytics 画面を開き、「コスト」「支出レポート」に相当する CSV エクスポートを実行する。期間は当月（MTD）。ユーザーごとの「使用量」画面ではなく 分析画面にあることが多い。ユーザー行の「…」メニューには内訳が無いことが多いので注意。

CSV に必要な列は次の3つ。

列	用途
model（またはモデル名）	判定したいモデルの行を特定する
total_net_spend_usd（実課金額）	これがゼロなら定額内
total_cache_write_1h_tokens 等のキャッシュ列	後述の「本当のコスト要因」を見るのに使う

2-2. 判定する

対象モデルの行の実課金額を見るだけ。

• ゼロ → 定額内。罠2の裏返しで、従量課金される機能は上限に残枠があっても課金されるため、 「使ったのに金額がゼロ」は定額内以外に説明がつかない
• ゼロでない → 従量。金額の大きさは使用量次第なので、少額でも従量と判断する

注意: データは1日遅れが普通。当日に使った分は翌日にしか出ない。 「今日使ったのに金額が増えていない」は定額内の証拠にならない。翌日もう一度出す。

2-3. 総額の内訳も同時に見る（ここで別の発見が出る）

「請求額が想定より高い」という問題を追っているなら、支出レポートは原因の特定にも使える。 実例として、次のような分布が観測されている。

モデル	リクエスト	出力トークン	1時間キャッシュ書き込み	実課金
中位モデル	4,302	1,589,327	10,205,837	$8.64
上位モデル	3,263	2,744,158	307,694	$2.77

安いはずの中位モデルが上位モデルの3倍かかっていた。出力トークンは上位モデルのほうが多い。 差は1時間キャッシュの書き込み量（33倍）。長命キャッシュの書き込みは通常入力より単価が高く、 短命なセッションを大量に立てると読み出しで元が取れる前に書き込み料だけを払う。

つまり「安いモデルへ逃がす」だけではコストが下がらない。次を守る。

• 委譲は1セッションで複数件をまとめて処理させる。1件ずつ新セッションを立てると 同じ前提を毎回キャッシュに書き直す
• 短命・単発の呼び出しで長命キャッシュ（1時間 TTL）を狙わない
• 「安いモデルでも品質が保てる」という評価結果は品質の話であり、総額の結論ではない。 総額は支出レポートで別に測る

3. 確定した結果を機械が強制する形に落とす

人間向けドキュメントに「◯◯は監督用途のみ可」と書いても守られない。次の3層に落とす。

3-1. 単一の設定源を作る

判定結果を1つの JSONに集約する。判定に関わる全てのツールがこれを読む。 配布の仕組みに乗る場所（他PCへ同期されるディレクトリ）に置くのが要点。

{
  "planIncluded": true,
  "scope": "supervisor-only",
  "verifiedOn": "<YYYY-MM-DD>",
  "evidence": "支出レポート(<期間>): <モデルID> = <N> req, <M> out tok, 実課金 0.00。従量課金の機能は上限に関係なく課金されるため 0.00 は定額内を意味する。",
  "recheck": "分析画面の支出レポートを出し、当該モデルの行の実課金額が 0 でなくなったら planIncluded を false に戻す。プラン変更・シート種別変更時も再確認する。"
}

evidence と recheck を必ず書く。これが無いと半年後に「なぜ許可されているのか」が分からなくなり、 また推測でルールが書き換わる。

3-2. 読み込みヘルパーは「安全側に倒す」

export function loadPolicy(options = {}) {
  try {
    const dir = options.dir || path.dirname(fileURLToPath(import.meta.url));
    const raw = fs.readFileSync(path.join(dir, 'model-policy.json'), 'utf8');
    return JSON.parse(raw.replace(/^/, ''));  // BOM を除去する
  } catch {
    return { planIncluded: false, scope: 'supervisor-only' };  // 未確認は禁止扱い
  }
}

3点が要。

• ファイルが無い・壊れている場合は「禁止」に倒す。未確認のアカウントで勝手に課金させない
• BOM を除去する。Windows のシェルで書き出すと先頭に BOM が付き、除去しないと JSON.parse が落ちて禁止側に倒れ、「定額内なのに警告が出続ける」ことになる
• 読み込み元ディレクトリを引数で差し替えられるようにする。テストで両方の分岐を固定するため。 既定値はモジュール自身の位置から解決する（実行時のカレントディレクトリに依存させない。 配布先ではリポジトリの場所が違う）

3-3. 3か所で使い分ける

層	何を見るか	定額内のときの挙動
セッション監視（プロンプト送信時のフック）	自分の会話ログの末尾から現在のモデルを判定	何も言わない（正規の使い方になったので）
委譲の門（サブエージェント起動前のフック）	起動パラメータのモデル指定	拒否のまま（単価が高いモデルを量産に使わせない）
日次のコストレポート	期間内の使用量	警告ではなく情報として報告

「定額内だから全面解禁」にしないことが肝。単価が上位モデルの2倍あるようなモデルは、 定額内でも「設計・レビュー・検証（監督）に限る」に留めるのが費用対効果に合う。 scope: "supervisor-only" がその意思をコードで表現している。

セッション監視のフックは、会話ログ全体を読まない。実運用のログは数十MBになるので、 末尾の数百KBだけを読んで最新のモデルを判定する。

4. 検証（ここを飛ばすと必ず壊れる）

4-1. 実挙動を3経路とも叩く

単体テストだけでは足りない。フックに実際の入力を流して確認する。

# 定額内 → 無音であるべき
echo '{"session_id":"x","transcript_path":"<ログ>","hook_event_name":"UserPromptSubmit"}' | node session-guard.mjs

# 未確認 → 警告が出るべき（環境変数で policy を差し替える）
... | POLICY_DIR=<planIncluded:false のディレクトリ> node session-guard.mjs

# サブエージェント指定 → 定額内でも拒否されるべき
echo '{"tool_name":"Agent","tool_input":{"model":"<高単価モデル>"}}' | node agent-guard.mjs

4-2. CI が走らせている全部を手元で走らせる

よくある落とし穴: テストランナーのファイル名パターン（例 *.test.mjs）に乗っていない 検証スクリプトが CI の別ステップで走っていることがある。手元で --test を回して全部通っても、 CI で落ちる。着手前に CI 設定を開き、実行されているコマンドを全部列挙してから、 その全部を手元で流す。

既存の検証スクリプトが旧ルール前提の期待値を持っている場合は、 環境変数で「未確認」を明示して旧期待値を維持し、新たに「定額内なら無音」を1件足す。 旧期待値を消してはいけない（未確認アカウントの保護が効かなくなる）。

5. 委譲でこの作業をやらせる場合の注意

この作業を別の AI エージェントに委譲するなら、次の2つが実際に起きた失敗なので先に潰しておく。

失敗1: シェル経由の起動で引数が壊れる。 Windows で子プロセスを shell: true で起動すると引数がクォートされずに連結される。 -p "Please execute instructions:" のような空白を含む値が分割され、CLI が 使い方（ヘルプ）を表示して終了コード0で終わる。1行も書いていないのに成功に見える。

対処は「シェルを1層も通さない」だが、Windows では npm 製の CLI が .cmd なので shell: false にすると今度は EINVAL で起動できない。結論は「シェル経由は維持し、 引数の値に空白を入れない」。値を定数として切り出し、空白が入ったら落ちるテストで固定する。

失敗2: フォールバック先の空振りを検知していない。 主たる実行系が枠切れのときの代替経路は、主たる系と同じ検証を通さないと無言で失敗する。 「作業ツリーが1行も変わっていない」「出力にヘルプの文字列がある」を検知して非ゼロ終了させる。 終了コードだけを信じてはいけない。

失敗3: 委譲先が仕様の一部を落とす。 実測では、7項目の仕様を渡して2回連続で「テストの追加」だけが落ちた（宣言はするが実行しない）。 成果物のファイル一覧を突き合わせて確認し、落ちた項目は再委譲するか自分で埋める。 「完了報告に含めること」を仕様の末尾に明記しておくと突き合わせが速い。

6. 落とし穴チェックリスト

• 判定を支出レポートの金額でやったか（バーの有無・上限の残りで判断していないか）
• データが1日遅れであることを踏まえたか
• 設定ファイルが読めないとき禁止側に倒れるか
• BOM を除去しているか
• 設定ファイルの場所が配布の仕組みに乗るディレクトリか
• evidence と recheck を書いたか
• CI が走らせるコマンドを全部手元で流したか
• 旧ルール前提の既存テストを、消さずに「未確認」側で維持したか
• 実挙動を3経路（定額内・未確認・サブエージェント）叩いたか
• キャッシュ書き込み量も見て、安いモデルが実は高いを見落としていないか