agent-gate — fail-closed quality gate + hash-chained receipt ledger for agent work (stdio via PyPI)

agent-gate

AI エージェントが「完了」と宣言する前に、自分の作業をゲートできる MCP サーバーです。決定論的チェック、続いて独立した反証優先のレビュー、最後に改ざんを検知できる正直なレシートを提供します。

自分の課題を自分で採点するエージェントは、質の低い出力をリリースしてしまいます。agent-gate は、その規律をエージェントが実際に通過しなければならないツールにします。フェイルクローズのチェックリストと、追記専用のハッシュチェーンでつながれたレシート台帳です。エージェントオーケストレーションの指針である Fleet Mode を、実行可能なツールにしたものです。誇張ではなくレシートを、データ構造によって徹底します。

🧩 AI エージェントを効率的なコストで運用するための、5 つのリポジトリから成るコストガバナンススタックの一層です。bow は、すべての層を本番環境で実行するフラッグシップです。

agent: "done!"  ->  verify_gate(evidence)  ->  { passed: false, blocking: ["independent_refute_review", "no_secrets"] }

理由

エージェントシステムにおける高くつく失敗は、気づかれないものです。モデルのアップデートで出力の質が低下する、変更によってワークフローがひそかに壊れる、作業が間違っているのにエージェントが成功を宣言する、といった失敗です。解決策は、より賢いモデルではありません。エージェントが言い逃れできないゲートです。

• フェイルクローズ。 チェックは、明示的に真である場合にのみ満たされたとみなされます。証拠がなければ、証明にはなりません。（非公式なチェックではなく、昇格ゲートを模しています。）
• 改ざんを検知できるレシート。 各判断は (decision, metric, value, verdict) として記録され、sha256 チェーンにつながれます。過去のレシートを編集または削除すると、verify_chain() は false を返します。正直なログは善意ではなく、構造によって保証されます。
• デフォルトで人間が承認。 「取り消せない行為や外部への行為には人間の承認を得た」が必須のチェックです。エージェントが下書きを作り、人間が承認します。

ツール（MCP 経由）

ツール	内容
gate_checklist(name="ship")	完了を宣言する前にエージェントが満たすべきチェックリストを返します。
verify_gate(evidence, name="ship")	証拠をフェイルクローズで評価し、{passed, blocking} を返します。
record_receipt(decision, metric, value, verdict)	正直なハッシュチェーン付きレシートを追記し、そのレシートを返します。
read_receipts()	すべてのレシートと、チェーンが完全かどうかを返します。

デフォルトの ship ゲートには Fleet Mode が反映されており、deterministic_checks_pass、independent_refute_review、no_secrets、human_gated_if_irreversible、honest_receipt_logged が含まれます。

MCP クライアントへのインストールと接続

pip install mcp-agent-gate   # or: pip install -e . (from source)

MCP クライアント（Claude Desktop / Claude Code）の設定に追加します。

{
  "mcpServers": {
    "agent-gate": { "command": "python", "args": ["-m", "agent_gate.server"] }
  }
}

これで、エージェントが完了を伝える前に verify_gate(...) を呼び出せるようになり、エージェントが下した判断の改ざんを検知できる記録が残ります。レシートは ~/.agent-gate/receipts.jsonl に保存されます（AGENT_GATE_LEDGER で変更できます）。

直接使用する（MCP クライアントは不要）

from agent_gate.gate import DEFAULT_SHIP_GATE
from agent_gate.ledger import Ledger

res = DEFAULT_SHIP_GATE.evaluate({
    "deterministic_checks_pass": True,
    "independent_refute_review": True,
    "no_secrets": True,
    "human_gated_if_irreversible": True,
    # honest_receipt_logged missing  ->  fail-closed
})
print(res.passed, res.blocking)   # False ['honest_receipt_logged']

led = Ledger("receipts.jsonl")
led.append(decision="ship v0.1", metric="tests", value="pass", verdict="shipped")
print(led.verify_chain())         # True  (until someone edits the log)

設計

• テスト済みの標準ライブラリのみのコア。 agent_gate/gate.py（フェイルクローズのチェックリスト）と agent_gate/ledger.py（ハッシュチェーン形式のレシート）は標準ライブラリのみで実装されているため、すばやく読めて、安心して信頼できます。agent_gate/server.py はこれらを利用する薄い MCP アダプターです（唯一の実行時依存関係は mcp です）。
• テストは Python 3.11～3.13 で合格します（CI を参照）。 MCP ツールはインポートするだけでなく、実際に呼び出してテストしています。

テスト

pip install -e ".[dev]" && python -m pytest -q

デモ

自分で実行してみましょう：PYTHONPATH=. python3 examples/demo.py

------------------------------------------------------------
1. Agent claims done — but two checks are missing
------------------------------------------------------------
{
  "passed": false,
  "blocking": [
    "human_gated_if_irreversible",
    "honest_receipt_logged"
  ]
}

------------------------------------------------------------
2. Agent satisfies all five checks
------------------------------------------------------------
{
  "passed": true,
  "blocking": []
}

------------------------------------------------------------
3. Record a hash-chained receipt
------------------------------------------------------------
{
  "seq": 1,
  "decision": "ship v0.1",
  "verdict": "shipped",
  "hash": "015202a168512f15..."
}
{
  "seq": 2,
  "decision": "deploy",
  "verdict": "approved",
  "hash": "9533d304d4dd07e5..."
}

------------------------------------------------------------
4. Verify the chain — edit receipts.jsonl to see this flip to False
------------------------------------------------------------
chain_intact: True

このリポジトリ自身にもゲートを適用

agent-gate は未検証の作業をリリースしないことを目的としているため、このリポジトリ自体にも同じ基準を適用しています：

• カバレッジでゲートされたテストマトリックス — ci.yml は Python 3.11～3.13 で pytest を実行し、行カバレッジがしきい値（現在は 97%）を下回るとビルドを失敗させます。
• CodeQL — 静的解析（security-extended）をすべてのプッシュ、PR、および毎週実行します。検出結果は Security タブに表示されます。
• 固定されたサプライチェーン — すべての GitHub Actions は完全なコミット SHA に固定されています。Dependabot が固定バージョンと Python の依存関係を最新の状態に保ちます。
• ブランチ保護 — main へのマージには、CI と CodeQL のチェックへの合格が必須です。
• 脆弱性開示ポリシー — SECURITY.md を参照してください。

貢献

CONTRIBUTING.md を参照してください。

概要

Jeff Otterson (Jott2121) が開発しました。agent-gate は、bow（Claude のみを使う自律型のチーフ・オブ・スタッフエージェント）と Fleet Mode のドクトリンに基づくゲート適用の規律を運用可能にします。同じ系統の関連プロジェクトには、rag-guard と agent-cost-attribution があります。MIT ライセンスです。

補完ツール

sabot は、このアイデアの測定を担います。agent-gate がエージェントのワークフローにフェイルクローズのゲートを追加する一方、sabot は実行中の LangGraph、CrewAI、AutoGen のパイプラインに制御された障害を仕込み、こうしたゲートやレビュー担当ステージが実際に作動するかを測定します。本番環境の 3 つのフレームワークにおける自己チェックの検出率の中央値は 16.7% です。事前登録済みの仕様、Apache-2.0 ライセンスのハーネスが用意されており、すべての生トレースが公開されています。