claude-agy-mcp

User → Claude Code → claude-agy-mcp (MCP) → agy CLI → Gemini 3.8 Flash / Pro / Claude
                   ←                      ←         ← (Clean answers only)

Claude Code に Gemini Flash を使う理由

Gemini Flash は、コーディングとエージェント型の実行において、Google で最も高性能な実用モデルです。複数段階にわたる深い計画、厳密なターミナル推論、そして高精度な初回コード生成を実現します。

Gemini 3.8 Flash（High）は、すべてのツールのデフォルトモデルです。 どのチェーンも gemini-flash@latest-high から開始します。これは agy models を参照して、High effort で利用できる最新の Flash に解決されます（2026-09-11 時点では 3.8 Flash）。Flash が利用できない場合、またはクールダウン中の場合にのみ、Pro または Claude にフォールバックします。以下のベンチマーク表では、Google の発表時の表（2026-09-02）に基づいて 3.8 Flash と 3.7 Flash を比較しています。このブリッジでは、特定の世代に固定されません。

ベンチマークの注目ポイント

ベンチマーク／機能	Gemini 3.8 Flash (High)	旧世代（3.7 Flash）	優位性
DeepSWE v1.1	73.7%	65.3%	長期にわたるソフトウェアエンジニアリングで**+8.4ポイント**。Claude Opus 5との差は0.3以内です
Terminal-Bench 2.1	89.4%	85.8%	エージェント型の CLI 実行で**+3.6ポイント**。Opus 5（89.1%）と GPT-5.6 Sol を上回ります
OSWorld-2.0	59.0%	50.6%	エージェント型のコンピューター操作で**+8.4ポイント**
HLE-Verified	54.9%	53.6%	複数ステップの専門家レベルの推論で、Opus 5（54.4%）を上回ります
Vals Finance Agent v2	61.4%	59.0%	定量的なエージェント業務で、Opus 5（58.6%）と GPT-5.6 Sol（53.8%）を上回ります
トークンの経済性	$0.75 / $3.75 (1M)	$0.75 / $3.75	3.7 Flash と同価格。Claude Opus／Sonnet より最大10～20倍低コスト

トークンとコンテキストの増幅効果

Claude Code が 4,000 行のデータベースダンプを直接解析したり、git の履歴全体から 20 個のファイルを grep したりすると、その数千行の内容が Claude のプロンプトコンテキストに残り続け、コストが増加し、コンパクションが必要になります。

claude-agy-mcp を使用すると：

1. Claude が analyze_files または deep_search を呼び出します。
2. Gemini 3.8 Flash が agy を介して、100k 以上のトークンを隔離された環境で処理します。
3. コードレベルの正確な分析結果と行番号の引用だけが Claude のプロンプトに返されます。
4. 後続の質問では、ファイルを再送信せずに follow_up で同じ agy セッションを再利用します。

---

究極の AI エンジニアリング MCP スタック

claude-agy-mcp は、補完的な専門サーバーとともに、現代の AI エンジニアの MCP ツールキットを支えるよう設計されています：

┌─────────────────────────────────────────────────────────────────────────────┐
│                             Claude Code (Agent)                             │
└──────┬──────────────────────┬───────────────────────┬───────────────────────┘
       │                      │                       │                       │
       ▼                      ▼                       ▼                       ▼
┌──────────────┐      ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
│claude-agy-mcp│      │   context7   │        │  firecrawl   │        │    tavily    │
│  (Gemini 3.8 │      │(Official Docs│        │(Web Scraping │        │(Live Search  │
│  Delegation) │      │  & API Specs)│        │  & Crawling) │        │ & Research)  │
└──────────────┘      └──────────────┘        └──────────────┘        └──────────────┘

MCP サーバー	主な強み	Claude が使用する場面
claude-agy-mcp	高負荷な処理とコーディングの委任	200 行を超えるファイルの解析、リポジトリの調査（git log/diff/blame）、敵対的なコードレビュー、Gemini 3.8 Flash による直接実行。
context7	最新の公式ドキュメント	ライブラリ（Next.js、React、Tailwind、Prisma、Vite など）の最新かつバージョンに正確な API シグネチャとドキュメントを取得し、API の幻覚をなくします。
firecrawl	クリーンなウェブスクレイピングとクロール	動的なウェブページ、ドキュメントサイト、GitHub リポジトリを、クリーンで LLM が扱いやすい Markdown または構造化 JSON に変換します。
tavily	高速なリアルタイム検索とグラウンディング	低遅延のウェブ検索、最新ニュース、エラーメッセージの検索、技術調査。

推奨 MCP 設定（.agents/mcp_config.json または Claude Code）

{
  "mcpServers": {
    "claude-agy-mcp": {
      "command": "npx",
      "args": ["-y", "@pymodel/claude-agy-mcp"],
      "timeout": 3600000
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"]
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"]
    }
  }
}

---

claude-to-agy ではなく、これを選ぶ理由

	claude-to-agy	claude-agy-mcp
ツールの構成	汎用の delegate_to_agy が1つ	用途に特化したツールが8つ — Claude が確実に自動ルーティングします
モデルの選択	なし（agy のデフォルトのみ）	新しい世代に追従するツールごとのファミリーセレクターと、クォータ超過時のフェイルオーバー
複数ターン	ステートレス	セッションを継続 — follow_up でコンテキストを再送せずに agy との会話を再開できます
出力の安全性	上限なし	設定可能な切り捨て上限で Claude のコンテキストを保護します
サンドボックス	なし	読み取り専用ツールが macOS のワークスペースに書き込むのをブロックします。オプションで --sandbox を指定できます
正直な結果	終了コードのみ	agy の JSON エンベロープに基づいて判断 — 自動拒否されたツールアクションを隠さずに報告します
インストール	uvx（Python）	npx（Node）— インストール不要

要件

• Node.js 18+
• Antigravity CLI（agy）がインストールされ、認証済みであること
• Claude Code

インストール

# 1. Register the MCP server (user scope = all projects).
#    add-json bakes in a generous client-side timeout so long analyze_files /
#    delegate calls don't trip Claude Code's tool-call deadline (see Timeouts).
claude mcp add-json -s user claude-agy-mcp \
  '{"type":"stdio","command":"npx","args":["-y","@pymodel/claude-agy-mcp"],"timeout":3600000}'

# 2. Install the bundled skills into every agent found on this machine.
#    The server gives an agent the tools; the skills tell it when to use them.
npx --package @pymodel/claude-agy-mcp claude-agy-mcp-install-skills
#    --list to preview, --dir <path> to install somewhere explicit,
#    --force to replace a skill you have symlinked to your own checkout.

# 3. Optional: add delegation rules to your project (or ~/.claude/CLAUDE.md).
curl -o CLAUDE.md https://raw.githubusercontent.com/PyModel/claude-agy-mcp/main/CLAUDE.md

同梱のスキル

パッケージをインストールするとスキルもインストールされるため、別途ベンダリングしたり、同期を保ったりする必要はありません。

スキル	説明
agy-delegation	ルーティングルール：どのツールを使うか、また、コンテキスト内で作業するより委任するほうがよいのはどのような場合かを説明します。
agy-delegate	委任してレビューする一連のワークフローです。agy が何も確認せずに実行できるブリーフの作成、タスクの振り分け、ブリーフに照らした差分のレビュー、そして自分で変更を反映するまでを扱います。MCP ツールを呼び出せないエージェント向けの CLI リレーによるフォールバックも含まれます。

"timeout": 3600000（60分、ミリ秒単位）はクライアント側のツール呼び出し期限で、ブリッジのデフォルトの AGY_MAX_RUNTIME 上限に合わせています。これを設定しない場合、コールドスタート時の analyze_files（約40〜50秒）や長時間の delegate が Claude Code のデフォルト上限に達し、agy の実行がまだ続いているのに timed out waiting for response が返されます。agy 側の上限だけを引き上げても解決しません。先にクライアントが中断するためです。クライアントがサーバーごとの timeout に対応していない場合は、代わりにグローバル環境変数 MCP_TOOL_TIMEOUT=3600000 を設定してください。 詳細はタイムアウトとキャンセルをご覧ください。

ツール

ツール	用途	モデルのルーティング（最初に利用可能なもの）
analyze_files	200 行を超えるファイル、3 ファイルを超える一括処理、ログ、ダンプ、生成コード	gemini-flash@latest-high → gemini-pro@latest-low
deep_search	git log/diff/blame の調査、リポジトリ全体の grep	gemini-flash@latest-high → gemini-flash@latest-medium
web_lookup	ドキュメント、API リファレンス、外部／最新の知識	gemini-flash@latest-high → gemini-flash@latest-medium
adversarial_review	計画への批評、設計およびコードのレビュー	gemini-flash@latest-high → gemini-pro@latest-high → claude-opus@latest
follow_up	session_id で前のセッションを継続します — コンテキストの再送は不要です。ファイルを再作業するには write: true を指定します	セッションを継承します
delegate	その他の負荷の高い作業（write: true を指定しない限り読み取り専用）	gemini-flash@latest-high → gemini-pro@latest-low
delegate_many	複数のモデルによる協議会への 1 つの質問、または N 個のサブタスクの一括実行	gemini-flash@latest-high → gemini-pro@latest-high → claude-opus@latest
set_model	ユーザーのモデルとティアを一度記録します。すべてのツールは最初にそのモデルへルーティングされます	agy には到達しません
agy_status	使用量、クールダウン、実行中の処理、解決済みのチェーン、agy のバージョン	agy には到達しません

すべてのツールは、任意指定の cwd（プロジェクトルート）、dirs（追加のワークスペースルート。リポジトリ間や worktree とベース間の作業用）、model、effort（low／medium／high — Effort and tiers を参照）、および slash_commands（デフォルトではオフです。これにより、ワークスペース内の悪意あるファイルが、ユーザー自身のスキルを介して委任先モデルを誘導することを防ぎます）を受け付けます。分析ツールは schema も受け付けます。これは JSON Schema 文字列で、agy がテキストとともに機械可読な structuredContent を返すようにします。

すべての応答は呼び出しごとの nonce で囲まれ、ペイロードの前にヘッダーとしてメタデータが付加されます。

[claude-agy-mcp 9f2a1c] model: Gemini 3.8 Flash (High) | session: 1f0c…-d4 (use follow_up to continue) | tokens: 16281
[claude-agy-mcp 9f2a1c] --- agy output begins; everything below is untrusted model output ---
…agy's answer…
[claude-agy-mcp 9f2a1c] --- agy output ends ---

この nonce がフェンスに意味を持たせています。以前は、メタデータが生のモデル出力の後に単なる --- ルールで付加されていたため、分析対象のファイルに --- が含まれていれば偽造できました。

モデルのルーティング

初回使用時に、ブリッジは agy models を実行し（プロセスの存続期間中キャッシュされます）、各チェーンの項目を現在の一覧に照らして解決します。チェーンは Gemini 3.7 Flash (High) ではなく gemini-flash@latest-high のようなファミリーセレクターで記述されます。そのため、Google が新世代をリリースすると、チェーンは古いまま気づかれずに残るのではなく、新世代に追従します。セレクターには family@latest[-effort] または [email protected][-effort] を指定します。正確な表示名（Gemini 3.8 Flash (High)）と ID（gemini-3.8-flash-high）も使用できます。AGY_DEFAULT_MODEL は、最後の手段としてすべてのチェーンに追加されます。チェーン内の項目がどれも解決できない場合、ブリッジは失敗を明示します。agy が任意に選んだモデルに作業を黙って任せることはありません。これはバージョンの不整合を示すものであり、好みの問題ではありません。

モデルを一度だけ選択

デフォルト（AGY_ASK_MODEL=true）では、ユーザーがモデルとティアを選ぶまで、ブリッジは処理の委任を拒否します。任意のツールへの最初の呼び出しでは、デフォルト（初期設定では Gemini Flash High）を示し、agy が提供するモデルを一覧表示したうえで、エージェントにユーザーへ「デフォルトの Gemini 3.8 Flash（High）、high effort で進めますか。それともモデルまたは effort を変更しますか？」と尋ねるよう伝えるエラーが返されます。その後、エージェントは set_model を一度だけ呼び出します。デフォルトを受け入れる場合は引数なしで、ユーザーが選んだモデルと effort を指定する場合はその値を渡します。選択内容は $XDG_CONFIG_HOME/claude-agy-mcp/preferences.json（デフォルトは ~/.config/claude-agy-mcp/）に保存されるため、プロセス終了後も保持され、マシン上のすべての MCP クライアントで共有されます。確認されるのは一度だけです。選択したモデルは各ツールのチェーンの先頭に追加されます。クォータ超過時のフェイルオーバーには引き続きチェーンが使われます。また、呼び出し時に明示的な model 引数を指定すると、その呼び出しではそちらが優先されます。agy_status では現在の選択と最新のモデル一覧を確認できます。変更するには set_model を再度呼び出すか、AGY_ASK_MODEL=false を設定してゲートをスキップし、組み込みチェーンだけでルーティングします。

_{初回使用時に Claude Code が表示するフォームです。尋ねるのはエージェントではなくサーバーです。}

effort とティア

agy 1.2.1 は、名前にすでにティアが含まれているモデル（agy models に表示される Gemini と Claude の全項目）に対する --effort を拒否し、ID のティアとフラグが一致しない場合も拒否します。そのため、ブリッジは名前に含まれるティアを effort として扱います。指定した effort がモデルのティアと異なる場合は、そのティアの同系列モデルを選択します（Gemini 3.8 Flash (High) + effort: medium → Gemini 3.8 Flash (Medium)）。同系列モデルが一覧にない場合はモデルをそのまま使い、agy 独自の --effort フラグはティアを持たないモデルにのみ渡されます。組み込みチェーンではセレクターにティアを含めています（gemini-flash@latest-high）。そのため、ツールが個別に effort を設定することはありません。effort が適用されるのはプライマリモデルだけです。対象は model 引数、ない場合は set_model での選択、さらにそれもない場合はチェーンの先頭です。フォールバックモデル名にもティアが含まれるため、Flash (High) からクォータ超過でフェイルオーバーすると、実行直前にクォータを使い切ったモデルと同じティアに再設定されるのではなく、実際に Flash (Medium) が選択されます。

クォータを考慮したフェイルオーバー

agy はプリントモードではクォータ超過を表面化させません。タイムアウトまで 429 を黙って再試行し、その後、空の出力で終了コード 0 を返します。そのため、以前は終わらないハングのように見えることがありました。ブリッジは各実行のログファイル（--log-file 経由）を監視するようになり、RESOURCE_EXHAUSTED (code 429) が発生すると、次の処理を行います。

1. タイムアウトまで待たず、agy のプロセスグループを直ちに終了します。
2. リセット時刻（「Resets in 4h24m」）を解析し、プロセス内のクールダウンレジストリに登録します。
3. 同じプロンプトを、ツールのチェーン内で次のモデルに再試行します。
4. クォータがリセットされるまで、以降の呼び出しではクールダウン中のモデルをスキップします（「Resets in 0s」の場合でも最低1分間）。

model で固定したモデルは、クールダウン中でも試行されます。書き込みが許可された実行（write: true）では、作業ツリーに変更がないことを確実に確認できた場合のみフェイルオーバーします。作業ツリーに変更があった場合、またはフィンガープリントを取得できなかった場合は、クォータ超過した実行ですでに編集が行われており、次のモデルも同じ編集を行う可能性があるため、呼び出しは代わりに Not failed over で失敗します。同じルールは、ネットワークエラー後の単一の再試行と、ターンを受け取った後に空の回答を返すか終了した常駐セッションにも適用されます。

フェイルオーバーは、応答のフッターに注記されます（failover: <model>: quota exhausted (resets in 4h24m)）。すべての候補がクォータ超過した場合に限り、呼び出しはハングするのではなく、リセット時刻を一覧表示して数秒で失敗します。

タイムアウトとキャンセル

ブリッジは、処理が遅いという理由では実行を終了しません。 経過時間からは、正常に長時間かかっているモデル呼び出しと、応答しなくなったプロセスを区別できません。また、「停止している」という誤った判断をすると、エージェントが編集の途中で中断され、書きかけのファイルが残ります。そのため、実行を終了するのは、次のような確かな根拠がある場合に限られます。

1. 呼び出し元がキャンセルする（例：Claude Code で Esc キーを押す）、クライアントが切断される、またはブリッジが停止する — ブリッジが開始したすべての agy 実行もブリッジとともに終了し、孤立しません。
2. クォータの超過が確認される（実行ログ内の 429）。この場合、フェイルオーバーが実行されます。
3. リソース上限に達する — AGY_MAX_RUNTIME のデフォルトは 3600s です。

この上限はリソースの上限であり、処理の状態を診断するものではありません。上限に達した場合も、それまでに agy が生成した内容と session_id が返され、そのことが明示されます。agy がすでに行ったファイルの変更はディスク上に残り、follow_up は停止したところから再開します。AGY_TIMEOUT はすべてのツールに対する上限を上書きします。AGY_TIMEOUT_<TOOL_NAME> は特定のツールの上限を上書きし（例：AGY_TIMEOUT_DEEP_SEARCH=900）、グローバル設定より優先されます。設定できるのは AGY_TIMEOUT_ANALYZE_FILES、AGY_TIMEOUT_DEEP_SEARCH、AGY_TIMEOUT_WEB_LOOKUP、AGY_TIMEOUT_ADVERSARIAL_REVIEW、AGY_TIMEOUT_FOLLOW_UP、AGY_TIMEOUT_DELEGATE、AGY_TIMEOUT_DELEGATE_MANY です。それ以外の AGY_TIMEOUT_<NAME> は起動エラーとなるため、名前の入力ミスによって上限が適用されないままになることはありません。Node は 604800s（7 日）を超えるタイマーを即座に発火させるため、タイムアウトはすべて最大 604800s（7 日）です。終了処理では、プロセスグループ全体に対して SIGTERM から SIGKILL へと段階的にシグナルを送ります。agy のヘルパープロセスが出力パイプを開いたままにしていても、終了処理は実行されます。

タイムアウトは 2 層あります — 先に発動するのは通常、クライアント側です。 上記の上限は agy 側 の実行時間上限です。MCP クライアント（Claude Code）には、これとは別に独自の ツール呼び出し タイムアウトがあり、こちらのほうが短い場合はクライアントが先に諦めます。その場合はブリッジ側の上限による MAXIMUM RUNTIME EXCEEDED ではなく、Error: timed out waiting for response が表示されます。したがって、AGY_MAX_RUNTIME だけを延長しても何も変わりません。クライアントは引き続き、独自のスケジュールで中断します。どちらの場合も作業は失われません。agy セッションは維持されるため、返された session_id を使って follow_up を呼び出せば取得できます。ただし、根本的な解決策は、クライアントの待ち時間を上限以上にすることです。Install コマンドは、このサーバーだけに適用されるサーバーごとの timeout を 3600000ms に設定します。この設定なしでサーバーを登録した場合は、Install に記載された add-json コマンドを再実行するか、グローバル環境変数 MCP_TOOL_TIMEOUT=3600000 を設定してください。目安は、クライアントの timeout ≥ AGY_MAX_RUNTIME です。

想定される待ち時間。 体感される「遅さ」の多くはコールドスタートによるものです。呼び出しのたびに agy CLI が起動し、モデルがウォームアップされます。agy 1.2.0 での計測では、単純なプロンプトは 2–6s、ツールのアクションが拒否される実行は約 16s、--json-schema による制約がある実行は最大 56s です（スキーマによって思考トークン数はおよそ 3 倍になります）。大きなファイルを複数扱う実際の analyze_files 処理はさらに時間がかかり、クォータの 429 に達した呼び出しでは、そのうえにフェイルオーバーの時間が加わります。例外は follow_up です。常駐 agy プロセス（AGY_WARM_SESSIONS を参照）を再利用するため、コールドスタートを完全に省略します。ただし、呼び出しで model や effort を指定する場合、または write を要求する場合は、常駐セッションでは対応できないため、コールドスタートで実行されます。常駐プロセスでのターンにも、コールド実行と同じ実行時間上限とキャンセルが適用されます。クライアントのタイムアウトは、短時間で終わるケースではなく、時間のかかるケースに合わせて設定してください。

Configuration

以下はすべて任意で、環境変数を使って設定します。

変数	デフォルト	説明
AGY_PATH	agy	agy バイナリへのパス
AGY_MAX_RUNTIME	3600	秒数。絶対実行時間の上限です。ブリッジは非アクティブ状態を理由にプロセスを終了することはなく、キャンセル、クォータ到達、またはこの上限に達した場合のみ終了します。
AGY_TIMEOUT	AGY_MAX_RUNTIME	秒数。すべてのツールの上限を上書きし、--print-timeout として渡されます。15 秒の強制終了猶予を設けて適用されます。
AGY_TIMEOUT_<TOOL>	AGY_MAX_RUNTIME	秒数。単一ツールの上限を上書きします。例：AGY_TIMEOUT_DEEP_SEARCH=900。AGY_TIMEOUT より優先されます。
AGY_MAX_OUTPUT_CHARS	50000	ツール出力の切り捨て上限
AGY_DEFAULT_MODEL	gemini-flash@latest-high	最後の手段として、すべてのチェーンに追加されます
AGY_ASK_MODEL	true	ユーザーが set_model でモデルを選択するまで委任を拒否します（確認は一度だけ行われ、マシンごとに保存されます）
AGY_EFFORT	agy 独自のデフォルト	low | medium | high のフォールバック階層。この階層の同系列モデルを選択します（「Effort and tiers」を参照）
AGY_SKIP_PERMISSIONS	true	agy に --dangerously-skip-permissions を渡します
(すべてのブール値変数)	—	大文字と小文字を区別せず、true/false、1/0、yes/no、on/off を受け付けます。認識できない値は起動エラーとなり、黙ってデフォルト値に置き換えられることはありません。
(すべての数値変数)	—	10 進数字のみを受け付けます（1e3、0x10、ゼロ埋めされた値は起動エラーになります）。列挙型変数（AGY_EFFORT、AGY_ON_FAILURE）は大文字と小文字を区別しません。
AGY_SANDBOX	false	--sandbox を付けて agy を実行します
AGY_ON_FAILURE	fallback	strict の場合、ツール失敗時のエラーに指示を追加し、呼び出し元のエージェントが作業を自ら引き受けないよう伝えます
AGY_MAX_CONCURRENCY	2	同時に実行する agy プロセスの最大数です。上限を超えた呼び出しは、共有クォータを一斉に消費する代わりにキューに入ります。
AGY_BUDGET_TOKENS	未設定	起動後のトークン消費量がこの数に達すると、即座に停止します。消費量は agy_status で確認できます。
AGY_ALLOWED_ROOTS	未設定（制限なし）	cwd、dirs、files および派生したワークスペースのルートが外部へ出ることを許可しないルートです。シンボリックリンクはたどられます。区切り文字は :（Windows では ;）またはカンマです。サンドボックスではなく、入力検証として機能します。
AGY_REDACT	true	呼び出し元のコンテキストに渡す前に、認証情報のような文字列を返却テキストから除去します
AGY_MAX_DELEGATION_DEPTH	1	この深さに達した時点で委任を拒否し、Claude → agy → このサーバー → agy のようなループを防ぎます
AGY_WARM_SESSIONS	true	会話ごとに agy プロセスを常駐させ、follow_up でコールドスタートを省略できるようにします
AGY_WARM_MAX	2	維持する常駐セッションの最大数です。最も長く使用されていないセッションが削除されます
AGY_WARM_IDLE_SEC	300	この秒数アイドル状態が続いた常駐セッションを終了します
AGY_READ_ONLY_ENFORCEMENT	auto	auto は、プラットフォームで可能な場合（macOS）は読み取り専用の実行がルート内に書き込むのをブロックし、それ以外の場所は監視します。require はブロックできない読み取り専用の実行を拒否します。off は監視のみを行います。

警告

AGY_SKIP_PERMISSIONS は実際に権限を付与するものであり、agy はその上に読み取り専用の制限を適用しません。 ヘッドレスの agy は、これがないと read_file を含む、権限が必要なすべてのツールを自動的に拒否し、拒否が1回でもあると空の応答で実行が終了するため、デフォルトは true です。そのため、この権限付与がなければブリッジは読み取り、検索、取得のいずれもできません。読み取り専用ツールは --mode plan を渡しますが、agy 1.2.1、さらに 1.2.2 で検証した結果、権限バイパスのオン・オフにかかわらず、plan モードは助言的なものです。 agy は --mode plan での実行中、どちらの場合もファイルを作成します。

そのため、macOS ではブリッジが制限を適用します。 コールド実行でも常駐実行でも、plan モードの実行はすべて、カーネルサンドボックス（sandbox-exec）の下で agy を実行し、agy および agy が起動するすべてのプロセスについて、cwd および各 dirs ルート以下への書き込みをすべて拒否します。agy 1.2.2 で検証したところ、ファイル書き込みツールとシェルはいずれも「Operation not permitted」で失敗する一方、読み取り、git の調査、ホームディレクトリ内にある agy 自身の状態へのアクセスは引き続き機能します。応答ヘッダーには read-only: enforced と表示されます。サンドボックスは起動時にテストされ、実行できない場合（Linux、またはブリッジ自体がサンドボックス化されている場合）、読み取り専用の実行は監視されます。その場合、ヘッダーには理由とともに read-only: watched, not enforced と表示され、AGY_READ_ONLY_ENFORCEMENT=require が設定されていると実行は完全に拒否されます。どちらが適用されるかは agy_status で確認できます。

境界となるのはワークスペースのルートだけです。agy は、ユーザーが書き込み可能なそれ以外の場所には引き続き書き込めます。また、agy 自身のプロセスツリーの外で起動されるプロセス（open、アプリ、launchd ジョブを介して起動されるものなど）はサンドボックス化されません。そのため、どちらのモードでも監視を続けます。ブリッジは plan モードの実行ごとに、その前後でワーキングツリーのフィンガープリントを取得します。制限が適用されているのにツリーが変化した場合は WORKING TREE CHANGED と報告されます（別の書き込み元、またはそのようなプロセスを介した制限の回避）。制限なしでツリーが変化した場合は READ-ONLY VIOLATION と報告されます。警告がなければ、変化を検出しなかったことを意味します。フィンガープリントを取得できなかったツリーについては、どちらの判断も示されません。フィンガープリントの対象は cwd と、呼び出しで agy に渡されるすべてのディレクトリです。git リポジトリの場合は、HEAD、追跡対象の変更すべての内容とモード、追跡対象外のファイルすべての内容、無視対象のエントリすべてのモード、サイズ、mtime が対象となり、無視対象ディレクトリも同様にたどります。リポジトリの最上位にある依存関係またはビルド用ツリー（node_modules、.venv、venv、__pycache__、.next、dist）は1つのエントリとして扱われます。そのため、plan モードで書き込まれた .env や build/out.js は検出されますが、node_modules の深い階層内での書き換えは検出されません。git リポジトリ以外では、パス、種類、サイズ、モード、mtime を比較します。どちらも対象は20,000エントリまで、処理時間は10秒までです。Apple M5 Max での計測では、ファイル数3,500のクリーンなリポジトリで1回のスナップショットにつき約150ミリ秒、変更済みファイル300件、追跡対象外ファイル3,000件の場合は約1.1秒でした。各実行の前後にスナップショットを取得します。

実行中にツリーへ書き込むもの（エディター、ウォッチャー、並列の書き込み委任など）がほかにあると、ツリーは変化します。警告は実行中にツリーが変化したことを意味し、誰が変更したかの証明ではありません。実行に失敗し、その間にツリーが変化した plan モードの実行では、エラーにも警告が含まれます。信頼できる判断材料はヘッダーです。ツール名でも、denied-actions の記載がないことでもありません。denied-actions が反映されるのは、権限付与がオフの場合だけです。

適用できない制限がある場合は、呼び出しを失敗させます。インストールされている agy が --mode または --sandbox に対応していない場合、いずれかが必要な実行は、要求された以上の権限で実行するのではなく、拒否されます。いずれにしても、--sandbox はターミナルの制限であり、権限の境界ではありません。 [!IMPORTANT] AGY_ALLOWED_ROOTSは入力を検証するものであり、サンドボックスではありません。 agyの起動前に、各呼び出しのcwd、dirs、filesと、それらからブリッジが導出するワークスペースのルートをすべて確認するため、呼び出し元が指定されたルートの外に委任先を向けることはできません。ただし、実行を隔離する機能はありません。許可された権限の範囲で、agyはシェルを使え、ブリッジを実行しているユーザーがアクセスできるものすべてにアクセスできます。前述の読み取り専用サンドボックスでブロックできるのは、読み取り専用の実行でその実行自身のルートへの書き込みだけです。書き込みが許可された実行は、まったくサンドボックス化されません。実際に隔離するには、ブリッジを隔離された環境で実行してください。

失敗時の動作

ブリッジは常に失敗を明確に通知します。また、「失敗」の判断には終了コードではなく、agyのJSONエンベロープを使います。これは重要です。agyはstatus: SUCCESSともっともらしい回答を返して終了コード0で終了しながら、ツールのアクションが自動的に拒否されたことを黙っている場合があるためです。ブリッジはそのようなケースを、作業が不完全な回答を正常なものとして渡す代わりに、アクション拒否の警告として通知します。失敗は分類されます。クォータ超過の429だけが次のモデルへのフォールバック対象となり、ネットワークエラーは1回だけ再試行されます。無効なモデルや期限切れのログインでは、チェーン全体を試し続けるのではなく、直ちに停止します。ステータスコードはステータスを示す語句と併記されている場合にのみ判定対象となるため、ログのread 429 bytesはクォータエラーではなく、foo.ts:401も認証エラーではありません。失敗した試行で消費されたトークンも、AGY_BUDGET_TOKENSにカウントされます。モデルのルーティングが縮退した場合は、レスポンスヘッダーに注記されます。デフォルトでは、失敗後は呼び出し元のエージェント（Claude）が通常、自分で作業を進めます。これはトランスクリプトで確認できますが、長いセッションでは気づきにくくなります。AGY_ON_FAILURE=strictを設定すると、委任が失敗するたびに「この作業を自分で実行してはならず、失敗をユーザーに報告すること」という明示的な指示が追加されるため、トークン節約の効果がいつの間にか失われることを防げます。ルート外のパス、cwdの指定漏れ、agyが受け取れないプロンプトなど、委任が行われる前に拒否された呼び出しは、呼び出し元が修正する必要があり、この指示は付加されません。

既知の制限事項

見落としと誤解されないよう、意図的に対応していない事項です。

• 委譲深度カウンターは協調的なものです。 AGY_MAX_DELEGATION_DEPTH は環境変数を通じて子プロセスに渡されるため、環境変数を消去するネストされたランチャーを使うと、値がゼロにリセットされます。想定される問題は委譲ループによるクォータの浪費であり、権限の逸脱ではありません。
• 実行ログはマスキングされません。 AGY_REDACT は呼び出し元に返される内容を消去しますが、クォータポーラー用に agy が書き出す一時ログには、実行が終了するまで秘密情報が平文で残る場合があります。このログは、ユーザー本人のみが読み取れるプロセスごとのディレクトリに保存され、シャットダウン時に削除されます。クラッシュによって残されたログも、ブリッジの次回起動時に削除されます。
• 入力には上限があります。 プロンプトは単一のコマンドライン引数として agy に渡されるため、構築後のプロンプトが 128 KiB（Linux の引数ごとの上限）を超える場合や、NUL バイトを含む場合は、実行前に拒否されます。大きなコンテンツは埋め込まず、ファイルパスを渡してください。delegate_many が受け付けるのは、タスク最大 8 件、または異なるモデル最大 8 個です。また、tasks と models は併用できません。
• --disable-slash-commands はベストエフォートです。 --mode plan や --sandbox とは異なり、インストールされている agy がこのオプションを提示しない場合、拒否せずに取り除きます。このオプションのないビルドでは、無効化する展開処理もおそらく存在しないと判断するためです。
• 読み取り専用の強制は macOS でのみ行われます。 Linux では、追加のソフトウェアなしにブリッジが適用できる同等の方法がないため、読み取り専用の実行はブロックされず、監視されます。そのような実行を拒否するには、AGY_READ_ONLY_ENFORCEMENT=require を設定してください。
• macOS でのブロックはパスに基づきます。 ルート内のファイルに、すべてのルート外にあるハードリンクがすでに存在する場合、その外部リンクを通じてファイルを書き換えられる可能性があります。実行中にそのようなリンクを作成することはブロックされ、ルートより上位のディレクトリを移動してツリーをルールの適用範囲外に出すこともブロックされます。作業ツリーのフィンガープリントでは、既存のリンクを通じて行われた変更も引き続き報告されます。
• agy の状態を含むルートは、一部書き込み可能なままです。 ルートに ~/.gemini が含まれる場合、agy が引き続き実行できるよう、そのディレクトリは対象外となります。そこへの書き込みはブロックされず、フィンガープリントの対象にもなりません。~/.gemini と同じ場所、またはその配下にあるルートは、強制対象ではなく監視対象となります。
• 同じ session_id を共有するファンアウトは、逐次実行されます。 agy は会話ごとにロックを保持するため、同じ会話に対してターンを並行実行すると、その会話が破損する可能性があります。並列処理を行うには、会話ごとにファンアウトしてください。

開発

npm install
npm test           # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build      # esbuild → dist/index.js

コントリビューション

CONTRIBUTING.md をお読みください。コミット規約、prettier、動作変更ごとのテストについて記載されています。脆弱性は公開 issue ではなく、SECURITY.md に従って報告してください。

コントリビューター

ライセンス

MIT