agents-shipgate 0.13.0

The deterministic merge gate for AI-generated agent capability changes. Agent release readiness for tool-using AI agents. CLI + GitHub Action. Scans MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain, CrewAI, OpenAI API, Codex config, Codex plugin, n8n.

Agents Shipgate

Your coding agent changed what your AI agent can do — Agents Shipgate tells you whether it can merge.

The deterministic merge gate for AI-generated agent capability changes.

Local-first and static by default — no agent execution, tool calls, LLM calls, or network access.

60 seconds: watch it block two PRs

Claude Code adds stripe.create_refund to your support agent and opens a PR. The diff looks fine to a human skimming it. Should it merge?

uvx agents-shipgate fixture run ai_generated_refund_pr

→ merge_verdict: blocked — the new refund capability has no declared approval policy and no idempotency evidence. The verifier explains both blockers and routes the PR to a human.

Now the move every reviewer fears — the agent deletes the Shipgate CI gate to make its PR pass:

uvx agents-shipgate fixture run agent_weakens_gate

→ merge_verdict: blocked, can_merge_without_human: false. The gate-removal checks are suppression-immune: the cheapest reward-hack is also the most visible one.

One engine decides (report.json.release_decision.decision); everything else — merge_verdict, PR comments, Check Runs, Action outputs — is a deterministic projection of it. Five-minute version: docs/mental-model.md.

Agents Shipgate is an open-source CLI and GitHub Action for local-first, static Tool-Use Readiness review. It scans MCP, OpenAPI, OpenAI Agents SDK, Anthropic Messages API, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex repo config, Codex plugin, and n8n artifacts, then writes a deterministic Tool-Use Readiness Report before your agent gets production-like permissions.

Within agent release readiness, Agents Shipgate's wedge is Tool-Use Readiness: the tool surface, schemas, scopes, approval policies, idempotency, and blast radius reviewed at PR time.

Website: threemoonslab.com — quickstart, glossary, check catalog, and design partners.

Static-by-default — no agent execution, no LLM calls, no MCP server connections, no scanner network calls, no scanner telemetry. Audited exceptions are pinned in tests/test_adapter_static_only.py::ALLOWED_EXCEPTIONS. Apache-2.0.

What your PR sees

When a PR changes what your agent can do, the GitHub Action posts the merge verdict as a PR comment. This is the comment for the first demo PR above — the coding-agent diff that adds stripe.create_refund to a support agent (abridged from the verbatim pr-comment.md artifact):

Agents Shipgate result: block

Decision: block · Risk: critical · Required reviewers: agent-platform, security

Impact	Change	Subject	Why
blocks release	action added	stripe.create_refund	Capability added.
blocks release	action broadened	stripe.create_refund	high-risk effect financial_action added
blocks release	scope broadened	stripe.create_refund:stripe:*	scope added

Required before merge — Actor: Human (human authority required — a coding agent must not self-resolve):

1. Declare an approval policy for stripe.create_refund or remove this tool from the release.
2. Declare approval.required, safeguards.audit_log, and safeguards.idempotency for this financial write action.
3. Replace wildcard/admin scopes with operation-specific scopes.

Then re-verify: agents-shipgate verify --base origin/main --head HEAD --json

The same uvx agents-shipgate fixture run ai_generated_refund_pr command above writes this comment verbatim to reports/pr-comment.md.

Verify-first quickstart

The core loop is verify-first: when a PR changes what your agent can do, run the deterministic verifier on the diff and read its merge verdict before you merge.

First ask whether Shipgate applies to the current repo or diff:

agents-shipgate verify --preview --json

If the repo is not configured yet, install the manifest, advisory CI, and agent-facing instructions:

agents-shipgate init --workspace . --write --ci --agent-instructions=default --json

Prefer to delegate? Paste the coding-agent snippet into Claude Code, Codex, or Cursor and let the agent wire the gate itself — the repo ships AGENTS.md managed blocks, llms.txt, and structured error output for exactly this path.

Then verify the committed PR/CI ref. Pass the base and head so the diff — the capability delta and trust-root signals — is in scope (the verifier never fetches; make the base ref available first, e.g. git fetch origin main):

agents-shipgate verify --workspace . --config shipgate.yaml \
  --ci-mode advisory --format json --base origin/main --head HEAD

For local, uncommitted work, omit --base/--head so your working-tree edits are scanned instead:

agents-shipgate verify --workspace . --config shipgate.yaml \
  --ci-mode advisory --format json

The release gate is agents-shipgate-reports/report.json → release_decision.decision (blocked | review_required | insufficient_evidence | passed). The PR/controller surface is agents-shipgate-reports/verifier.json → merge_verdict (mergeable | human_review_required | insufficient_evidence | blocked | unknown), a deterministic projection of the release decision. Read verifier.json first for merge_verdict, can_merge_without_human, first_next_action, fix_task, and capability_review.top_changes.

Want a 5-minute verifier demo with zero setup? Run the verify-native blocked refund PR fixture:

agents-shipgate fixture run ai_generated_refund_pr

To see the trust-root defense itself — a coding agent deleting the Shipgate CI gate to make its PR pass, and the verifier blocking the merge — run:

agents-shipgate fixture run agent_weakens_gate

The expected verdict is blocked with can_merge_without_human: false: the gate-removal checks are suppression-immune, so the cheapest reward-hack is also the most visible one.

It builds a temporary base/head git history where the head commit adds stripe.create_refund, then writes verifier.json, report.json, and pr-comment.md. The expected merge verdict is blocked.

The older static scan fixture remains useful when you want the full Tool-Use Readiness Report without a PR diff. If you already have uv installed, the fixture path is a one-command install check with no persistent install:

uvx agents-shipgate fixture run support_refund_agent

Otherwise, install once with pipx and run the same fixture:

pipx install agents-shipgate
pipx upgrade agents-shipgate
agents-shipgate --version
agents-shipgate fixture run support_refund_agent

The fixture prints:

Fixture: support_refund_agent
Decision: blocked
Blockers: 2  Review items: 16
Counts:  critical=2 high=14 medium=2
Reports: <tempdir>/reports
Fixture copy at <tempdir>; pass --keep to retain after the run.

Both blockers are on stripe.create_refund: missing approval policy and missing idempotency evidence. The fixture writes report.{md,json} and packet.{md,json,html} into the temp reports/ directory. To verify your own repo and write the standard agents-shipgate-reports/ directory, see Verify your repo below.

How to read your first result

For PR verification, read verifier.json.merge_verdict first:

Merge verdict	Meaning	Next step
blocked	Active, unaccepted blockers exist.	Fix blockers or remove the risky capability.
insufficient_evidence	Static evidence is too weak to gate release confidently.	Add better sources and rerun; do not auto-merge.
human_review_required	A person must review accepted debt, trust-root changes, or authority-bearing gaps.	Surface the required review; a coding agent must not self-approve it.
mergeable	No active blocker or review signal was found.	Keep verifier/report artifacts with the PR record.
unknown	Verify could not produce a reliable head scan or diff context.	Fix setup, fetch the base ref, or rerun with usable inputs.

Then read report.json.release_decision.decision, the source-of-truth gate:

Decision	Meaning	Next step
blocked	Active, unaccepted blockers exist.	Fix the blockers or remove the risky tool surface.
insufficient_evidence	The scan cannot confidently gate release from the available static evidence. This does not prove the agent is unsafe.	Provide clearer sources such as an MCP export, OpenAPI spec, explicit local tool inventory, or broader OpenAI SDK source path, then rerun.
review_required	Human review is needed, often for accepted debt or evidence gaps below the blocked threshold.	Review the listed items before promotion.
passed	No active blocker or review signal was found.	Keep the report artifact with the PR/release record.

Common review signals include missing confirmation, missing idempotency evidence, broad-scope permissions, prohibited-action policy gaps, and trust-root changes such as weakened CI or manifest policy.

GitHub Action Marketplace

The public Action is listed on the GitHub Action Marketplace. Use the snippet in Use in CI to add it to a workflow.

Not sure if Shipgate applies?

Run the zero-install detector from the repo you are reviewing. It is a stdlib-only first touch for engineers and coding agents that need a yes/no relevance signal before installing anything:

curl -sSL https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/tools/shipgate-detect.py \
  | python3 - --workspace . --json

Continue to Verify your repo when the output has is_agent_project: true, non-empty suggested_sources, non-empty codex_plugin_candidates, or the workspace already has shipgate.yaml.

Sample reports

Open a report first if you want to see the output shape before installing:

Sample	Markdown	JSON
support_refund_agent	report.md	report.json
simple_openai_api_agent	report.md	report.json
simple_langchain_agent	report.md	report.json

The support_refund_agent fixture also includes a reviewer-shaped Release Evidence Packet in packet.md, packet.json, and packet.html.

Copy this into your coding agent

Add a Tool-Use Readiness release gate for this tool-using AI agent with Agents Shipgate.
Run:
agents-shipgate verify --preview --json
If Shipgate is relevant, run:
agents-shipgate init --workspace . --write --ci --agent-instructions=default --json
agents-shipgate verify --workspace . --config shipgate.yaml \
  --base origin/main --head HEAD --ci-mode advisory --format json
For local uncommitted work, omit `--base`/`--head`. For committed PR/CI refs,
make the base ref available first because `verify` never fetches. Read
`agents-shipgate-reports/verifier.json` first and lead with `merge_verdict`,
`can_merge_without_human`, `first_next_action`, `fix_task`, and
`capability_review.top_changes`, then read
`agents-shipgate-reports/report.json` for `release_decision.decision`. Do not
claim completion when `merge_verdict` is `blocked`, `insufficient_evidence`, or
`human_review_required` unless the user explicitly accepts human review. Do not auto-assert approval. Do not auto-assert confirmation, idempotency,
broad-scope safety, prohibited-action enforcement, runtime-trace proof,
suppressions, waivers, baselines, or policy weakening. Never remove Shipgate CI
or weaken agent instructions just to make the verifier pass.

Use with Claude Code

Two commands wire the full Claude Code surface:

pipx install agents-shipgate
agents-shipgate init --workspace . --write --claude-code

init --claude-code writes the CLAUDE.md managed block, the auto-discoverable .claude/skills/agents-shipgate/ skill, an agents-shipgate verify --json alias in Makefile / package.json scripts when present, and the Claude Code hooks (also available standalone via agents-shipgate install-hooks --target claude-code --write). The hooks run a cheap trigger check after Edit|Write|MultiEdit and the full verifier at Stop — so Claude Code re-checks agent capability changes before reporting work complete, even on long sessions where instruction files lose attention. CI stays authoritative; the hooks are the local feedback loop.

Inside Claude Code, agent mode auto-enables (the harness exports CLAUDECODE=1), so a zero-flag agents-shipgate verify prints the compact agent result on stdout: merge_verdict, can_merge_without_human, suggested_fixes, and agent_repair_instructions in one call.

See docs/agents/use-with-claude-code.md for the /shipgate slash command, skill internals, and manual install paths.

Install the Codex plugin

Agents Shipgate now ships a skill-only Codex plugin package at plugins/agents-shipgate/ with a repo marketplace entry at .agents/plugins/marketplace.json. The plugin lets users install Agents Shipgate from Codex, start a new thread, invoke $agents-shipgate, and have Codex run the existing CLI workflows for detect, init, verify, scan, report reading, and finding triage.

Add this repository as a Codex marketplace source, then install Agents Shipgate from Codex's Plugins view:

codex plugin marketplace add ThreeMoonsLab/agents-shipgate

For local checkout validation:

codex plugin marketplace add /path/to/agents-shipgate

After installation, start a fresh Codex thread and invoke:

$agents-shipgate verify this agent PR and summarize the merge verdict.

The plugin supplies Codex workflows, not the scanner binary. Install or upgrade the CLI in the environment where Codex will run commands, then confirm agents-shipgate --version reports 0.13.0 or newer:

pipx install agents-shipgate
pipx upgrade agents-shipgate  # plain install is a no-op over a stale build
agents-shipgate --version

If pipx is unavailable, use:

python -m pip install -U "agents-shipgate>=0.13"
agents-shipgate --version

The v1 launch channel is workspace sharing from the Codex app or this repo-backed marketplace. Public/OpenAI-curated listing remains an optional later platform submission.

Early testers who installed the old agents-shipgate-beta marketplace should remove that marketplace and reinstall from agents-shipgate:

codex plugin remove agents-shipgate
codex plugin marketplace remove agents-shipgate-beta
codex plugin marketplace add ThreeMoonsLab/agents-shipgate
codex plugin add agents-shipgate@agents-shipgate

Add the Codex adoption kit

For OpenAI Codex repos, install both the native AGENTS.md trigger block and the repo-scoped Codex skill:

agents-shipgate init --workspace . --write --agent-instructions=agents-md,codex-skill

The skill lives at .agents/skills/agents-shipgate/, can be invoked with $agents-shipgate, and teaches Codex the verify, bootstrap, report-reading, advisory CI, and finding-triage workflows.

To customize generated skill content in a downstream repo without rebuilding agents-shipgate, add .agents-shipgate/adoption-kit.yaml with repo-local overrides, or pass it explicitly:

agents-shipgate init --workspace . --write \
  --agent-instructions=codex-skill \
  --agent-instructions-kit .agents-shipgate/adoption-kit.yaml

Who this is for

• Agent builders — review MCP, OpenAPI, and SDK tool definitions before merging changes that expand the tool surface.
• Platform teams — add release gates for approval, scope, idempotency, and baseline drift to PR review.
• Security and GRC reviewers — get static release evidence without running agents or importing user code.

Use this when

Run Agents Shipgate when a PR adds or changes agent tool surfaces or the policy evidence around them:

• MCP exports, OpenAPI specs, or local tool inventories.
• OpenAI Agents SDK, Google ADK, LangChain/LangGraph, CrewAI, Anthropic Messages API, or OpenAI API artifact tool definitions.
• Codex repo config such as .codex/config.toml or .codex/hooks.json.
• Prompts, permission scopes, approval policies, confirmation policies, prohibited actions, or shipgate.yaml.
• GitHub Actions or CI release gates for a tool-using AI agent.

Verify your repo

agents-shipgate verify --preview --json
agents-shipgate init --workspace . --write --ci --agent-instructions=default --json
# Replace any CHANGE_ME placeholders reported by init.
agents-shipgate verify --workspace . --config shipgate.yaml \
  --base origin/main --head HEAD --ci-mode advisory --format json

For local uncommitted work, omit --base/--head. For committed PR/CI refs, make the base ref available first because verify never fetches. Verify writes agents-shipgate-reports/verifier.json, pr-comment.md, the head capability lock, and the normal report.{md,json,sarif} / packet artifacts when a scan is required. If the base scan can be materialized, verify also writes base.capabilities.lock.json plus capability-lock-diff.{json,md}, and the PR comment includes a compact semantic capability diff summary. Lead with merge_verdict, can_merge_without_human, first_next_action, and the capability diff or capability_review.top_changes; use release_decision.decision as the release gate.

Install alternatives (your agent project does not need Python 3.12 — install the CLI separately):

python -m pip install -U "agents-shipgate>=0.13"    # global pip
uv tool install --upgrade agents-shipgate            # via uv
agents-shipgate --version                            # require >=0.13.0

Adopt in one turn (scan helper)

The verifier-first loop above is the product entry path. The older single-turn bootstrap flow remains useful when a coding agent needs a scan-oriented first adoption pass that can apply high-confidence manifest cleanup. It takes a workspace from "looks like an agent project" to "Shipgate integrated, scan green or with safe patches applied, CI workflow drafted":

agents-shipgate detect --json                                          # 1. classify
agents-shipgate init --write --ci --json                               # 2. manifest + workflow
agents-shipgate scan -c shipgate.yaml --suggest-patches --format json  # 3. scan + suggest
agents-shipgate apply-patches --from agents-shipgate-reports/report.json \
    --confidence high --apply                                          # 4. apply safe trivial fixes

init --ci writes .github/workflows/agents-shipgate.yml. apply-patches is dry-run by default and refuses to mutate anything outside the manifest's directory.

For agents driving this flow programmatically, see docs/agent-recipes.md. For framework-by-framework minimal manifests, see docs/minimal-real-configs.md.

Use in CI

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: ThreeMoonsLab/agents-shipgate@v0.13.0
  with:
    config: shipgate.yaml
    ci_mode: advisory
    diff_base: target
    pr_comment: "true"

The PR comment is fixed into a human summary plus agent instruction block, with merge_verdict, the semantic capability diff when available, required next action, and artifact links:

What it scans

Input	Status
Model Context Protocol (MCP) exports	Supported
OpenAPI 3.x specs	Supported
OpenAI Agents SDK Python files/directories	Supported
Anthropic Messages API artifacts	Supported
Google ADK Python and YAML config	Supported
LangChain/LangGraph static Python inputs	Supported
CrewAI static Python inputs	Supported
n8n workflow JSON and source-control stubs	Supported
OpenAI API artifacts	Supported
Codex repo config	Supported
Codex plugin packages and marketplaces	Supported

What it produces

When a PR changes what your agent can do, the verify loop writes these artifacts — in read order:

• agents-shipgate-reports/verifier.json — the primary, agent-facing artifact. A coding agent reads merge_verdict (mergeable | human_review_required | insufficient_evidence | blocked | unknown), can_merge_without_human, first_next_action, and fix_task to decide whether to continue, repair, or stop for a human. See docs/agent-contract-current.md for the field contract.
• agents-shipgate-reports/pr-comment.md — the human PR surface: the same verdict and semantic capability diff when available, shaped for a reviewer.
• agents-shipgate-reports/capabilities.lock.json + agents-shipgate-reports/base.capabilities.lock.json + agents-shipgate-reports/capability-lock-diff.{json,md} — the capability review primitive. Verify always emits the head lock after a successful scan; it emits the base lock and diff when the base scan can be materialized, falling back to the reviewed committed lock at .agents-shipgate/capabilities.lock.json if needed.
• Gate source of truth — report.json.release_decision.decision (passed | review_required | insufficient_evidence | blocked). merge_verdict is a deterministic projection of it; the report stays the one decision engine.
• Tool-Use Readiness Report (supporting) — agents-shipgate-reports/report.{md,json,sarif}. Markdown for human release review, JSON for tools and coding agents, SARIF for GitHub code-scanning workflows. This is the underlying check domain the verdict summarizes.
• Release Evidence Packet (supporting) — agents-shipgate-reports/packet.{md,json,html} (and packet.pdf with the [pdf] extras). Reviewer-shaped synthesis with fixed sections, including the compact evidence matrix plus tool-surface and action-surface diffs when available. Packet outputs are locally redacted by default; see STABILITY.md §Release Evidence Packet.

Exit codes

Code	Meaning
0	Pass (advisory mode or strict-no-blockers)
2	Manifest config error
3	Input parse error (file missing, malformed, path traversal blocked)
4	Other Agents Shipgate error
20	Strict-mode gate failure

For coding agents

Human readers can skip this section; it exists so coding agents can find the repo's machine-readable contracts quickly.

Agents Shipgate is designed to be agent-friendly. If you're a coding agent (Claude Code, Codex, Cursor, Aider) reading this repo:

• llms.txt — short index of every machine-readable surface, one fetch.
• llms-full.txt — long-form concatenation of AGENTS.md + recipes + checks + concepts + autofix policy, in one document. Built by scripts/build-llms-full.py.
• .well-known/agents-shipgate.json — discovery metadata (tagline, install commands, schema URLs, gating signal, exit codes, trigger-catalog URL).
• docs/triggers.json — machine-readable mirror of the AGENTS.md trigger table. Apply the rules to a PR diff to decide whether to propose agents-shipgate detect. Schema is stable for 0.x.
• tools/shipgate-detect.py — zero-install, stdlib-only detector. curl … | python3 - --workspace . --json returns the same structural verdict as agents-shipgate detect --json. Pinned to the canonical CLI by tests/test_zero_install_detector.py. See docs/zero-install.md.
• agents-shipgate contract --json — verify the installed CLI's local contract before relying on hard-coded schema or gating assumptions.
• docs/agent-contract-current.md — single source of truth for the current schema versions and which JSON fields to read. Updated whenever the contract bumps; other agent-facing surfaces link here instead of restating the contract.
• docs/agent-native-merge-contract.md — the agent-native protocol map: the eight contracts (trigger, capability change, merge verdict, repair, forbidden action, human authority, trust root, attestation) each mapped to the artifact that implements it.
• docs/capability-standard.md — stable non-gating capability lock/diff standard for external integrations and research tooling.
• docs/product-hardening-gap-closure.md — closure map for root dogfooding, the governance case catalog, policy-pack tests, trace evidence, and runtime-inventory boundaries.
• benchmark/agent-pr-governance/ + docs/governance-benchmark.md — stable research benchmark for unsafe-merge prevention, authority routing, and verifier explanation quality.
• AGENTS.md — canonical agent-facing instructions: install, run, common tasks, JSON-mode flags, error semantics
• STABILITY.md — what won't break across 0.x versions
• docs/target-repo-agent-snippets.md — copyable snippets for adding Shipgate trigger rules to downstream agent repos
• docs/agent-adoption-harness.md — manual protocol for checking whether coding agents discover and use Shipgate
• benchmark/ — frozen archetypes, prompts, setup variants, and a public leaderboard CSV. Closes the loop on adoption-readiness changes.
• docs/zero-install.md — single-file detector, uvx, and GitHub Action paths for evaluating Shipgate without a local install.
• prompts/ — reusable prompts for common workflows
• skills/agents-shipgate/ + .claude/commands/shipgate.md — self-contained Claude Code skill (bundled prompts and CI recipe) and /shipgate slash command. See docs/agents/use-with-claude-code.md to install in your own project.
• agents-shipgate install-hooks --target claude-code --write — deterministic Claude Code hooks: a PreToolUse trust-root guard, a cheap trigger check after Edit|Write|MultiEdit, and a full verify at Stop, so the gate runs even when instruction files lose attention on long sessions. See docs/agents/use-with-claude-code.md.
• agents-shipgate mcp-serve ([mcp] extra) — read-only stdio MCP server exposing shipgate.check, shipgate.preflight, shipgate.explain, and shipgate.capabilities for agents without comfortable shell access. It is static-only and not a general MCP permission broker. See docs/mcp-server.md.
• docs/ai-search-summary.md — human-readable summary for AI search, answer engines, and coding agents
• docs/manifest-v0.1.json + docs/report-schema.v0.26.json + docs/preflight-schema.v0.1.json — JSON Schemas for live editor validation and agent routing (current; emitted reports carry report_schema_version: "0.26" and preflight emits preflight_schema_version: "0.1"). v0.26 adds structured evidence gaps (release_decision.evidence_coverage.evidence_gaps[] — one actionable remediation row per low-confidence tool or source warning) plus the advisory suggested-inventory.json skeleton written next to report.json; gate behavior is unchanged. v0.25 added opt-in capability-linked local trace/provenance evidence (capability_runtime_evidence, findings[].capability_trace_refs, and mirrored ReleaseDecisionItem.capability_trace_refs) while preserving fingerprints, baselines, capability locks, and release gating. v0.24 added capability-native policy evidence (findings[].capability_refs, optional findings[].capability_policy_evidence, and mirrored ReleaseDecisionItem.capability_refs). v0.23 added semantic metadata to capability_change members while preserving the existing buckets and release gate. v0.22 added the verifier-cycle top-level blocks capability_change (diff-derived capability delta), protected_surface_changes (touched trust roots), effective_policy (normalized policy snapshot), human_ack (declared human-acknowledgement state), and verifier_summary (a composition over release_decision + the reviewer/agent summaries) — none of which gates independently. v0.21 added the top-level heuristics_filter envelope alongside v0.20's reviewer_summary block (lens + audit activity counts plus a first_recommended_surface pointer, parallel to agent_summary for the reviewer side); v0.19 added Finding.policy_evidence_source and ReleaseDecisionItem.{source, policy_evidence_source} for reviewer-grade dual-source provenance; v0.18 added privacy_audit; v0.17 added policy_audit and release_decision.contribution_rules[]. Read release_decision.decision for release gating in new consumers; read agent_summary.first_recommended_action for a deterministic next agent step and reviewer_summary.first_recommended_surface for the recommended human-review entry point.
• docs/capability-lock-schema.v0.2.json + docs/capability-lock-diff-schema.v0.3.json — stable schemas for the static capability envelope and semantic diff emitted by agents-shipgate capability and, in PR workflows, by agents-shipgate verify; non-gating and separate from report.json.
• docs/attestation-schema.v0.2.json — deterministic local attestation schema; v0.2 binds verifier artifacts plus capability lock/diff hashes when present.
• docs/governance-benchmark-catalog-schema.v0.2.json + docs/governance-benchmark-result-schema.v0.2.json — stable schemas for the research benchmark catalog and deterministic result artifact.
• docs/checks.json — machine-readable check catalog

Every command has a --json form. Errors emit a structured next_action line on stderr when agent mode is active — set AGENTS_SHIPGATE_AGENT_MODE=1, or rely on auto-detection inside a coding-agent harness (Claude Code exports CLAUDECODE=1, Cursor CURSOR_TRACE_ID). AGENTS_SHIPGATE_AGENT_MODE=0 forces it off.

Why this exists

Once an AI agent can refund, email, cancel, deploy, or modify a record, every tool change becomes a release event. Code review catches code; eval suites catch behavior; observability catches runtime. None of them answer the release question: given the tool surface declared in this PR, do we have explicit approval policies, scope coverage, idempotency evidence, and review readiness for every action?

Agents Shipgate produces a deterministic answer to that question, before promotion.

The current product promise is deliberately narrow: a deterministic, local-first, static merge gate for AI-generated agent capability changes — the Tool-Use Readiness review run at PR time. Broader lifecycle ideas are future roadmap work, not claims this scanner makes today.

Findings Gallery

The bundled support-refund fixture demonstrates the kind of release risks Agents Shipgate is designed to surface:

## Release Decision

Decision: blocked
Reason: 2 active findings block release.
Blockers: 2
Review items: 16
Fail policy: would_fail_ci=false (exit 0)

Top findings:
1. stripe.create_refund lacks a declared approval policy
2. stripe.create_refund lacks idempotency evidence
3. Manifest declares broad permission scopes

• stripe.create_refund lacks a declared approval policy, so a financial action could ship without an explicit human review gate.
• stripe.create_refund.amount lacks a maximum bound, weakening blast-radius control.
• stripe.create_refund lacks idempotency evidence while retry behavior is known, risking duplicate refunds.
• wildcard_mcp_tools.* exposes a wildcard tool surface, making review incomplete.
• gmail.send_customer_email overlaps a prohibited external-communication action without a matching confirmation policy.

See it block a PR

The fastest way to understand what changes for a reviewer: walk through a Golden PR. Each one ships a sample manifest, the resulting report, the release decision, and the recommended PR-comment summary an agent should post.

• openai-agents-sdk-refund-agent — refund agent adds stripe.create_refund. Shipgate decides blocked because approval policy and idempotency evidence are missing. Includes the recommended Markdown PR-comment template.
• golden-pr-from-coding-agent.md — the artifact a coding agent should produce after running the verify-first flow: PR comment, merge_verdict, capability_review, and human/coding-agent next action.
• mcp-only-tool-server — MCP server with no Python framework imports; demonstrates the MCP-only adoption path.
• openapi-support-agent — OpenAPI-described tool surface; shows scope-coverage findings.

Why Not Just...

Alternative	Gap Agents Shipgate Covers
Unit tests	Tests usually validate code paths, not the released tool surface and declared policies.
Code review	Reviewers miss generated specs, MCP exports, broad scopes, and missing approval policies.
Runtime traces	Useful later, but they arrive after behavior exists. Agents Shipgate runs before promotion.
Nothing	Tool-surface drift becomes a production surprise.

For named comparisons against specific evaluators and platforms, see the marketing-site versus pages: vs evals, vs promptfoo, vs Braintrust, vs LangSmith, and vs observability platforms.

CI Behavior

CI is advisory by default:

agents-shipgate scan --config shipgate.yaml --ci-mode advisory

Strict mode exits with code 20 only when unsuppressed critical findings exist. Configuration, input parsing, and internal tool errors use 2, 3, and 4 respectively:

agents-shipgate scan --config shipgate.yaml --ci-mode strict

For existing projects, save the current reviewed findings as a local baseline and fail strict CI only on new unsuppressed findings:

agents-shipgate baseline save --config shipgate.yaml --out .agents-shipgate/baseline.json
agents-shipgate scan --config shipgate.yaml --baseline .agents-shipgate/baseline.json --ci-mode strict

Teams can override severities and CI failure thresholds:

checks:
  severity_overrides:
    SHIP-AUTH-MISSING-SCOPE: critical
ci:
  fail_on:
    - critical
    - high

Google ADK

Agents Shipgate supports static Google ADK extraction for Python entrypoints and Agent Config YAML. The adapter detects LlmAgent/Agent definitions, function tools, OpenAPIToolset, McpToolset, callbacks, plugins, sub-agents, eval references, and explicit local tool inventories without importing ADK code.

version: "0.1"
project:
  name: adk-support-agent
agent:
  name: support-agent
  declared_purpose:
    - handle support cases
environment:
  target: production_like
tool_sources:
  - id: adk
    type: google_adk
    path: agent.py
google_adk:
  eval_sets:
    - evals/support.eval.json
  tool_inventories:
    - inventories/adk-mcp-tools.json

Dynamic ADK toolsets produce warnings or findings unless you provide explicit MCP, OpenAPI, or local tool inventory inputs.

LangChain And CrewAI

Agents Shipgate includes static Python extraction for LangChain/LangGraph and CrewAI. The adapters parse Python AST only; they do not import framework packages or user modules. The supported LangChain/LangGraph patterns target LangChain Core 0.3+, LangChain 1.x create_agent, and LangGraph 0.2+ source shapes.

tool_sources:
  - id: langchain_agent
    type: langchain
    path: agent.py
  - id: crewai_agent
    type: crewai
    path: crew.py

For dynamic or prebuilt tool surfaces, provide explicit local inventory files:

langchain:
  tool_inventories:
    - inventories/langchain-tools.json
crewai:
  tool_inventories:
    - inventories/crewai-tools.json

Policy Packs

v0.4 adds local declarative YAML policy packs for organization-specific release rules. Policy packs are static data and run without importing code.

checks:
  policy_packs:
    - path: policies/org-release.yaml

agents-shipgate scan --config shipgate.yaml --policy-pack policies/org-release.yaml

Who It Is For

Buyer	Pain	Pitch	Next step
Platform engineer shipping a first production agent	"I don't know what I don't know."	Audits manifest and tool schemas for release risks code review misses.	Run agents-shipgate init --workspace . --write.
Security or GRC reviewer	"Agents bypass existing controls."	Creates a static tool-surface audit trail for review.	Review the check catalog.
AI PM with a shipping deadline	"Security review blocks us late."	Gives teams self-serve pre-review before formal approval.	Scan the support-refund fixture.

Limitations

Agents Shipgate is a static, manifest-first scanner. It is intentionally narrow:

• It does not run agents, call tools, invoke LLMs, or verify model availability by default (static-by-default; see Trust Model and ALLOWED_EXCEPTIONS).
• It does not verify runtime behavior, latency, prompt quality, or routing decisions.
• It does not replace dynamic security testing or human security review of the underlying systems.
• It only inspects what is declared in shipgate.yaml, local OpenAPI specs, MCP exports, Anthropic/OpenAI API artifacts, optional SDK AST metadata, static Google ADK/LangChain/CrewAI/n8n inputs, Codex repo config, and static Codex plugin package metadata; tools that are not declared or statically discoverable are not scanned.
• The manifest remains version: "0.1" so existing configs keep working. Current reports carry report_schema_version: "0.26" (additive structured evidence gaps over v0.25's opt-in local trace/provenance evidence) while preserving the stable payload contract documented in the report schema.

See ROADMAP.md for what is planned next.

Trust Model

Agents Shipgate does not import user code, run agents, call tools, call LLMs, connect to MCP servers, make network calls, or collect telemetry by default.

See Trust model and Security policy for the default local-only guarantees and disclosure process.

GitHub Action

Drop this full advisory workflow into .github/workflows/agents-shipgate.yml. It runs on every PR, posts a summary comment, uploads the report and packet as workflow artifacts, and never fails the job. This is the same file shipped at examples/github-actions/01-advisory-pr-comment.yml.

name: Agents Shipgate (advisory)

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  shipgate:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
        with:
          fetch-depth: 0
      - uses: ThreeMoonsLab/agents-shipgate@v0.13.0
        with:
          ci_mode: advisory
          diff_base: target
          check_annotations: 'true'
          pr_comment: 'true'
          shipgate_version: '0.13.0'

After adoption, choose an explicit merge policy. examples/github-actions/07-block-on-blocked-verdict.yml blocks only when merge_verdict == blocked; examples/github-actions/08-require-mergeable.yml requires can_merge_without_human == true; examples/github-actions/11-fail-on-insufficient-evidence.yml fails only when merge_verdict == insufficient_evidence. See examples/github-actions/ for strict / baseline / SARIF / multi-config / changed-paths recipes.

Inputs: config, ci_mode (advisory or strict), fail_on, baseline, baseline_mode, diff_from, diff_base, base_ref, head_ref, policy_packs, no_plugins, output_dir, upload_artifact, check_annotations, check_annotation_limit, pr_comment, check_run, check_run_name, github_token, shipgate_version. Set check_run: true (with checks: write permission) to publish the merge verdict as a native Check Run with line-level SARIF annotations. Set diff_base: target for PR base/head diff enrichment. The action delegates to agents-shipgate verify and never fetches; use fetch-depth: 0 on checkout, or fetch the base ref in an earlier step. If head_ref is set, verify scans an isolated archive of that ref; otherwise it scans the checked-out workspace. If an explicit base ref or PR diff cannot be inspected, verify skips a head-only scan, writes merge_verdict: "unknown" to verifier.json, and exits 2.

Outputs: decision, merge_verdict, can_merge_without_human, blocker_count, review_item_count, ci_would_fail, diff_enabled, status, critical_count, high_count, medium_count, baseline_new_count, baseline_matched_count, baseline_resolved_count, adk_agent_count, adk_dynamic_toolset_count, trust_root_touched, policy_weakened, capability_changes_added, capability_changes_modified, capability_changes_removed, report_json, report_markdown, report_sarif, verifier_json, pr_comment_markdown, check_annotations_json, capability_lock_json, base_capability_lock_json, capability_lock_diff_json, exit_code. Use decision / ci_would_fail for CI gating, use merge_verdict / can_merge_without_human for PR-controller routing, and avoid legacy status for new gates.

The default PR comment is fixed into two sections: a human summary and a fenced JSON agent instruction block. The Action also emits source-backed GitHub Actions annotations for blockers and review items by default. verify writes capability lock/diff artifacts when a base ref is available; these remain non-gating review artifacts.

Set shipgate_version to install a pinned PyPI release instead of the action source when your workflow requires package/version parity.

For a design-partner review, export the small redacted verifier feedback artifact instead of sending raw report evidence:

agents-shipgate feedback export \
  --from agents-shipgate-reports/verifier.json \
  --redact \
  --out shipgate-feedback.json

Pricing And Open Source Stance

Agents Shipgate is and will remain free OSS for individuals and teams running it on their own infrastructure. The core manifest-first scanner, built-in checks, Markdown report, and JSON report are intended to remain open source. We do not collect telemetry and do not require an account.

If hosted dashboards, SSO, org-wide baselines, approval workflows, or trace-based evidence emerge, they should live in a separate optional product rather than moving core OSS functionality behind a paywall.

Teams shipping production-like tool-using agents can apply to the Three Moons Lab design partner program — the marketing page mirrors docs/design-partners.md in the repo and includes a prefilled email CTA for review criteria and contact. The current pilot runbook is docs/design-partner-verifier-pilot.md: bring one AI-generated agent PR, run the verifier loop, and export redacted feedback.

Docs

The marketing site at threemoonslab.com carries the same canonical concepts in human-readable, search-optimised form: quickstart, check catalog, glossary, blog, and design partners. The in-repo docs below are the canonical contract; the marketing pages are sized for first-time readers and AI search ingest.

• The 5-minute mental model
• MCP and host-permission governance
• MCP server mode
• Tool-Use Readiness release gate category
• Manifest v0.1
• Check catalog
• Policy packs
• Baseline workflow
• JSON report schema v0.26
• Capability standard
• Capability lock schema v0.2
• Capability lock diff schema v0.3
• Governance benchmark
• Feedback export schema v0.1
• Privacy and redaction
• Terms
• Trust model
• AI search summary
• Design partners
• Design partner verifier pilot
• Runtime inventory design note
• Troubleshooting
• Integration recipes
• Distribution plan
• JSON report schema v0.2
• JSON report schema v0.1