{
  "markdown": "<!-- mcp-name: io.github.Jott2121/agent-gate -->\n![agent-gate: gate an AI agent's work before it ships with deterministic checks, refute-first review, tamper-evident receipts](assets/banner.png)\n\n# agent-gate\n\n[![ci](https://github.com/Jott2121/agent-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/Jott2121/agent-gate/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/Jott2121/agent-gate/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jott2121/agent-gate/actions/workflows/codeql.yml)\n[![Coverage](https://raw.githubusercontent.com/Jott2121/agent-gate/python-coverage-comment-action-data/badge.svg)](https://github.com/Jott2121/agent-gate/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-blueviolet.svg)](https://modelcontextprotocol.io/)\n\n**An MCP server that lets an AI agent gate its own work before it claims \"done\": deterministic checks, then an independent refute-first review, then a tamper-evident honest receipt.**\n\nAgents that grade their own homework ship low-quality output. `agent-gate` turns that discipline into tools an agent must actually pass: a **fail-closed** checklist and an **append-only, hash-chained** receipts ledger. It is [Fleet Mode](https://github.com/Jott2121/fleet-mode), an agent-orchestration doctrine, made into a runnable tool. Receipts over hype, enforced by the data structures.\n\n> 🧩 One layer of a five-repo [**cost-governance stack**](https://github.com/Jott2121/bow#the-system-a-cost-governance-stack) for operating AI agents cost-efficiently; [bow](https://github.com/Jott2121/bow) is the flagship that runs every layer in production.\n\n```text\nagent: \"done!\"  ->  verify_gate(evidence)  ->  { passed: false, blocking: [\"independent_refute_review\", \"no_secrets\"] }\n```\n\n![agent-gate demo](assets/demo.gif)\n\n## Why\n\nThe expensive failures in agent systems are the silent ones: a model update degrades output, a change quietly breaks a workflow, an agent declares success while the work is wrong. The fix is not a smarter model. It is a gate the agent cannot talk its way past:\n\n- **Fail-closed.** A check counts as satisfied only if it is *explicitly* true. Missing proof is not proof. (Mirrors a promotion gate, not an informal check.)\n- **Tamper-evident receipts.** Every decision is recorded as `(decision, metric, value, verdict)` linked into a sha256 chain. Edit or delete any past receipt and `verify_chain()` returns false. The honest log is enforced by the structure, not by good intentions.\n- **Human-gated by default.** \"Any irreversible/outward act got human approval\" is a required check. Agents draft, humans approve.\n\n## Tools (over MCP)\n\n| Tool | What it does |\n|---|---|\n| `gate_checklist(name=\"ship\")` | Returns the checklist the agent must satisfy before claiming done. |\n| `verify_gate(evidence, name=\"ship\")` | Evaluates evidence **fail-closed** and returns `{passed, blocking}`. |\n| `record_receipt(decision, metric, value, verdict)` | Appends an honest, hash-chained receipt; returns it. |\n| `read_receipts()` | Returns every receipt plus whether the chain is intact. |\n\nThe default **`ship` gate** encodes Fleet Mode: `deterministic_checks_pass`, `independent_refute_review`, `no_secrets`, `human_gated_if_irreversible`, `honest_receipt_logged`.\n\n## Install & wire into an MCP client\n\n```bash\npip install mcp-agent-gate   # or: pip install -e . (from source)\n```\n\nAdd it to your MCP client (Claude Desktop / Claude Code) config:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-gate\": { \"command\": \"python\", \"args\": [\"-m\", \"agent_gate.server\"] }\n  }\n}\n```\n\nNow your agent can call `verify_gate(...)` before it tells you it is finished, and you get a tamper-evident trail of what it decided. Receipts persist to `~/.agent-gate/receipts.jsonl` (override with `AGENT_GATE_LEDGER`).\n\n## Use it directly (no MCP client needed)\n\n```python\nfrom agent_gate.gate import DEFAULT_SHIP_GATE\nfrom agent_gate.ledger import Ledger\n\nres = DEFAULT_SHIP_GATE.evaluate({\n    \"deterministic_checks_pass\": True,\n    \"independent_refute_review\": True,\n    \"no_secrets\": True,\n    \"human_gated_if_irreversible\": True,\n    # honest_receipt_logged missing  ->  fail-closed\n})\nprint(res.passed, res.blocking)   # False ['honest_receipt_logged']\n\nled = Ledger(\"receipts.jsonl\")\nled.append(decision=\"ship v0.1\", metric=\"tests\", value=\"pass\", verdict=\"shipped\")\nprint(led.verify_chain())         # True  (until someone edits the log)\n```\n\n## Design\n\n- **Tested, stdlib-only core.** `agent_gate/gate.py` (fail-closed checklist) and `agent_gate/ledger.py` (hash-chained receipts) are pure stdlib: fast to read, fast to trust. `agent_gate/server.py` is a thin MCP adapter over them (the one runtime dependency: `mcp`).\n- **Tests pass on Python 3.11-3.13 (see CI).** The MCP tools are tested by *calling them*, not just importing.\n\n## Tests\n\n```bash\npip install -e \".[dev]\" && python -m pytest -q\n```\n\n## Demo\n\nRun it yourself: `PYTHONPATH=. python3 examples/demo.py`\n\n```\n------------------------------------------------------------\n1. Agent claims done — but two checks are missing\n------------------------------------------------------------\n{\n  \"passed\": false,\n  \"blocking\": [\n    \"human_gated_if_irreversible\",\n    \"honest_receipt_logged\"\n  ]\n}\n\n------------------------------------------------------------\n2. Agent satisfies all five checks\n------------------------------------------------------------\n{\n  \"passed\": true,\n  \"blocking\": []\n}\n\n------------------------------------------------------------\n3. Record a hash-chained receipt\n------------------------------------------------------------\n{\n  \"seq\": 1,\n  \"decision\": \"ship v0.1\",\n  \"verdict\": \"shipped\",\n  \"hash\": \"015202a168512f15...\"\n}\n{\n  \"seq\": 2,\n  \"decision\": \"deploy\",\n  \"verdict\": \"approved\",\n  \"hash\": \"9533d304d4dd07e5...\"\n}\n\n------------------------------------------------------------\n4. Verify the chain — edit receipts.jsonl to see this flip to False\n------------------------------------------------------------\nchain_intact: True\n```\n\n## This repo gates itself\n\n`agent-gate` is about not shipping unverified work, so the repository holds itself to the same bar:\n\n- **Coverage-gated test matrix** — `ci.yml` runs pytest on Python 3.11–3.13 and fails the build if line coverage drops below the threshold (currently 97% covered).\n- **CodeQL** — static analysis (`security-extended`) runs on every push, PR, and weekly; findings surface in the Security tab.\n- **Pinned supply chain** — every GitHub Action is pinned to a full commit SHA; **Dependabot** keeps those pins and the Python deps current.\n- **Branch protection** — `main` requires the CI and CodeQL checks to pass before a merge.\n- **Disclosure policy** — see [SECURITY.md](SECURITY.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## About\n\nBuilt by **Jeff Otterson** ([Jott2121](https://github.com/Jott2121)). `agent-gate` operationalizes the gating discipline from [**bow**](https://github.com/Jott2121/bow) (an autonomous all-Claude chief-of-staff agent) and the [**Fleet Mode**](https://github.com/Jott2121/fleet-mode) doctrine. Siblings in the same line: [**rag-guard**](https://github.com/Jott2121/rag-guard) and [**agent-cost-attribution**](https://github.com/Jott2121/agent-cost-attribution). MIT licensed.\n\n## Companion instrument\n\n[sabot](https://github.com/Jott2121/sabot) is the measurement side of this idea. agent-gate\nadds a fail-closed gate to an agent workflow; sabot plants controlled faults inside running\nLangGraph, CrewAI and AutoGen pipelines and measures whether gates and reviewer stages like\nthese actually fire. Median own-check detection across three production frameworks: 16.7%,\nwith a pre-registered spec, an Apache-2.0 harness, and every raw trace published.\n",
  "bytes": 7917,
  "sha": "6c554afe1287cf7a46938861c12963f07628bd362bd8baa9a06935b4d9e1a082",
  "repo_slug": "jott2121/agent-gate",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jott2121_agent_gate_6c60a755/readme"
}