Skip to main content

トークン予算管理と安全な中止

更新 2026-10-08 7分で読めます GitHub で編集 ↗

トークノミクス4層構造のD層である予算防御(Budget defense)を深掘りします。エージェントがコンテキストウィンドウの限界に達したとき、セッションが停止せず、進行状況を保全しながら次のセッションが引き継げるようにする安全な中止(graceful abort)メカニズムを説明します。

プラットフォームの基礎
プラットフォーム層の背景については コンテキストウィンドウ を参照してください。MoAI-ADK としての説明はこのページです。

予算防御の必要性

Anthropic SSEストリームはコンテキストウィンドウの天井に近づくとstream_idle_partial状態で間欠的なストールを起こします。これは確率的ですが、しきい値以上で予測可能です。ストールが発生するとエージェント呼び出しがストリーム途中で失敗し、進行状況を失う可能性があります。

予算防御はこの問題を事前に解決します。コンテキスト使用量がしきい値に達する前にシステムが安全な中止を実行し、セッションが損失なく次のステップへ移行するように保証します。

モデルごとのコンテキストしきい値

運用しきい値はモデルごとに異なります。大きなウィンドウはより高いパーセンテージ利用を許容し、小さなウィンドウはパーセンテージでは後になりますが絶対ヘッドルームが少ないです。

モデルクラスウィンドウハンドオフしきい値絶対天井
Opus 5.5 (1M)1,000,000 トークン50%~500,000 トークン
GLM-5.3 (1M)1,000,000 トークン50%~500,000 トークン
Fable / Sonnet 5.5 (1M)1,000,000 トークン50%~500,000 トークン
Sonnet 4.5 以前 (200K)200,000 トークン90%~180,000 トークン
Haiku 5.5 (1M)1,000,000 トークン50%~500,000 トークン
Haiku (200K)200,000 トークン90%~180,000 トークン

Haiku 5.5 行(Claude Code v2.1.293+、Anthropic API)は上のルールと一緒に読みます — 1M 行と 200K セッション行の両方に該当する場合は 200K 行が優先されます。AWS Bedrock・GCP Agent Platform・Microsoft Foundry では haiku エイリアスは Haiku 4.5(200K)に解決されるため、AWS 系の Haiku セッションは引き続き 200K / 90% のしきい値に従います。

GLM-5.3(moai glm)は1Mコンテキストモデルなので50%しきい値で運用します。Claude Codeが報告するcontext_window_sizeはClaudeスロット基準(Opus=1M, Sonnet/Haiku=200K)なので、GLMセッションで生のtelemetryが~180Kを示してもMoAIが1Mに補正します。statuslineのCW%ゲージを信頼してください。

2段階ハンドオフマーカー

statuslineはコンテキストバーに/clearヒントを2段階で表示します。

  • ソフトマーカー — statuslineのコンテキストバーに/clearヒントが警告色とともに表示されます。バンドのソフトしきい値で現れ、ユーザーが判断して/clearを実行できる勧告シグナルです。
  • ハードマーカー — statuslineのコンテキストバーに/clearヒントが強い警告色とともに表示されます。auto-compact認識天井で現れ、次のアクションは必ず/clearでなければなりません。

ハード天井はauto-compactしきい値近くに設定されるため、ランタイムのauto-compactが先に発動してハードマーカーは実際には稀にしかトリガーされません。これはauto-compact認識公式の意図されたトレードオフです。

安全な中止手順

SPEC-TOKEN-BUDGET-STOP-001で実装された安全な中止メカニズムは次の手順で動作します。

  1. 検出 — Tracker.IsAtHardLimit(agentName)がtrueを返す (累積使用量 ≥ hard_clear_threshold、デフォルト0.90)
  2. 状態保存 — 進行中の作業状態をprogress.mdに永続化
  3. ハンドオフ発行 — ペースト可能なresumeメッセージを生成 (6ブロック構造)
  4. ターン終了勧告 — ユーザーに/clearを勧告 (HARD: 自動/clearは決して実行しない)
  5. 証拠の書き込み — 引用する検証証拠のうち判定を決めた行を、追跡対象の判定書.moai/reports/<card-id>/verdict.mdに書き込む

/clearは決して自動的に実行されません。システムはユーザーが/clearを実行するよう勧告のみを行い、ユーザーが判断して実行します。

paste-ready resume 6ブロック構造

セッションハンドオフメッセージは次の6ブロック構造に従います。各ブロックは次のセッションが最小限の情報で作業を続けられるように設計されています。

text
✂──── ここからコピー ────✂

ultrathink. <SPEC-ID> <phase> entering.
applied lessons: <memory-file-1>, <memory-file-2>

Preconditions:
1) <検証可能な前提 1>
2) <検証可能な前提 2>

Run: <コマンドまたはアクション>

After merge: <次のアクションまたはSPEC>

✂──── ここまでコピー ────✂

各ブロックの役割:

  • ブロック 1 — ultrathink.オープナーがeffort:xhighを設定し、進入するphaseとSPEC-IDを宣言
  • ブロック 2 — applied lessons: 前のセッションで学習したmemoryファイル参照 (最大4件)
  • ブロック 3 — Preconditions: 次のセッションが開始前に確認すべき検証可能な前提 (最大4件、各200字以内)
  • ブロック 4 — 個別の前提項目
  • ブロック 5 — Run: 単一の主要アクション (典型的には/moai <subcommand>)
  • ブロック 6 — After merge: 次のアクションまたはSPEC ID

検証ダイエット (verify-diet)

検証コマンドの長文出力をディスクにリダイレクトしコンテキストには要約のみ残すファイルリダイレクト契約(file-redirect contract)です。

ルール: 検証コマンドのverbatim出力がbounded-tail ceiling (デフォルト50行または2KBのいずれか小さい方)を超えると、出力をファイルにリダイレクトしコンテキストにはexit code + bounded tailのみ表示します。

bash
go test ./... > /tmp/moai-verify/1-go-test.log 2>&1; echo "exit=$?"; tail -50 /tmp/moai-verify/1-go-test.log

この契約は「ディスクにverbatim証拠を残し、コンテキストにはexit code + bounded tailのみ運搬」します。証拠を捨てるのではなく、インライン出力 + バナー再引用の二重消費(double-burn)を削除します。

検証証拠エクスポートの義務

ファイルリダイレクト契約が/tmpに書き込んだ証拠はOSによって定期的に削除されます(macOSリブート、Linux tmpfsリマウント、systemd-tmpfiles)。引用されたパスがもはやファイルとして存在しない場合、監査時に証拠に到達できません。

そこで検証出力は、まず.moai/state/verify/<session>/配下に置きます。ただしこのディレクトリはマシンローカルのスクラッチです — /tmpの消去は生き延びますが、context-usage/やactive-sessions.jsonと同じgitignoredのランタイム状態領域であり、cloneにもCIランナーにも他のマシンにも渡りません。/tmpを生き延びることと監査時点で到達できることは同じ意味ではありません。

そこで契約が定めるのは判定を決めた行を判定書に書き込む義務です。ある主張を立てるなら、その前にその行を追跡対象の判定書.moai/reports/<card-id>/verdict.mdに書き込み、引用はディレクトリではなくそのファイル1つを名指しします。カード ディレクトリで追跡される名前は判定書ひとつだけで、その隣に置いたファイルは無視されたままなので、それを引用すれば書いたツリーの外では開けません。書き込むのは判定を決めた行(終了コード、失敗の要約、引用する数値)だけです — スクラッチを丸ごと移せば、コンテキストから削った分量がリポジトリへ場所を変えるだけだからです。残したままの原文はスクラッチに置き、その損失の恐れを判定文の残余リスクの項に書き留めます。スクラッチに残したものを根拠として差し出してはいけません。

次のステップ