The problem

An LLM decides which tool to call and what to pass it. Nothing checks the arguments before they reach your code.

# Your tool expects an int. The model sends a string, and invents a parameter.
transfer_funds(amount="500", to="alice", force=True)
#                     ^^^^^              ^^^^^^^^^^
#                     wrong type         never in your signature

Type coercion turns "500" into 500 and moves on. The invented force=True lands in **kwargs and silently changes behaviour. Neither is a model failure you can prompt away — it is a missing contract at the call boundary.

Quickstart

pip install "agent-airlock>=0.10.3"

from agent_airlock import Airlock

@Airlock()
def transfer_funds(amount: int, to: str) -> str:
    return f"Sent ${amount} to {to}"

That is the whole integration. Now:

A blocked call returns a dict (AirlockResponse.to_dict()) rather than raising, so the model gets a refusal it can act on instead of a traceback it cannot.

What it does

The decorator runs a fixed sequence of gates before your function and sanitises after it. Validation, output sanitising and the audit log are on by default; the rest is opt-in.

Irreversible actions

These stop a call that passes validation but should not run yet, or should not run twice.

• SecurityPolicy(escalate_tools=..., approver=...) asks your approver before a matching tool runs, and the approval covers that call's exact arguments only. A denial, no answer within escalation_timeout_seconds, arguments changed while it waited or no approver refuses the call. @requires_human_oversight does the same for a plain function. Guide, tests, timeouts.
• Approvals given ahead of time go in an InMemoryApprovalLedger or SQLiteApprovalLedger with an expiry, and one call claims each, across processes with SQLite. The LangGraph, OpenAI Agents and PydanticAI adapters record theirs there. Tests.
• EffectGuard runs each tool_call_id at most once. A retry after a lost response gets the stored result, and it refuses a call whose outcome is unknown unless the tool is @reversibility("reversible"). Guide, tests.
• ActionContradictionGate holds back privileged tools once an operator-defined signal says the agent saw contradicting evidence. Tests.

None of this undoes an action that already ran, and airlock ships no approval channel: you connect the approver to Slack, a ticket queue or a prompt.

Token audience and startup hooks

Two checks that run before any argument is read:

• Token audience. AirlockConfig(expected_token_audience="https://mcp.example.test") checks the aud claim of the OAuth token behind every guarded call, read from the claims your server verified and put on AirlockContext(metadata={"access_token_claims": ...}), never from tool arguments. It warns by default; token_audience_mode="deny" refuses a token issued to another application, the bug in CVE-2026-115413.
• Startup hooks. startup_hook_check="warn" (or "deny") lists the executable .pth lines and sitecustomize / usercustomize of the running interpreter, once per process; deny refuses every call its config guards while one is not on startup_hook_allowlist. Those hooks ran before your code did, so this reports them; it cannot stop them.

Details: Token audience and startup hooks.

Shell and installer arguments

Nine MCP server CVEs published on 27 and 28 October 2026 share one shape: a string argument of an ordinary tool reaches a shell or a package installer on the server. CVE-2026-117558 (ai-sdlc, repo), CVE-2026-117559 (DroidMind), CVE-2026-117560 (ATXP), CVE-2026-117561 (sf-mcp), CVE-2026-117567 (esp-mcp, target, port, project_path), CVE-2026-117568 (mcp-ffmpeg), CVE-2026-117569 (Kali-GPT), CVE-2026-117573 (hagent, args) and CVE-2026-59176 (functype-mcp-server, version into pnpm add). ToolArgSinkGuard, off by default, reads those arguments on the call path, before the call reaches a server that builds a command line:

from agent_airlock import Airlock, SecurityPolicy, ToolArgSinkGuard

guard = ToolArgSinkGuard(shell_args={"repo"}, installer_args={"version"})


@Airlock(policy=SecurityPolicy(tool_arg_sink_guard=guard))
def check_issue(repo: str, version: str = "1.4.4") -> str:
    return f"checked {repo}"

repo="x; id" is refused (block_reason "tool_arg_sink"), and so is a version that is not a bare PEP 440 or npm semver version: a URL, a path, file: or npm:, pkg[extra]. screen_all_str_args=True screens every argument except free_text_args; policy_presets.tool_arg_sink_defaults() does that in warn mode first. Details: Shell and installer arguments.

dispatch_args covers an argument that names a function the tool then calls. Agno's PandasTools passed read_pickle to getattr(pandas, ...) that way (CVE-2026-119050): no shell syntax for the check above to see. ToolArgSinkGuard(dispatch_args={"operation": ("head", "describe")}) admits those names only; an empty allowlist refuses private names, *pickle*, read_*, to_*, eval, exec and their like. Preset: policy_presets.reflection_sink_defaults(dispatch_args=...), warn mode first. Details: Dispatch arguments.

Benchmarks

Every row is one command you can run. Dates are when the number was last actually produced, not when the row was last edited — check_benchmark_freshness.py fails the release if any row drifts past 30 days.

Table notes

Every airlock arm in rows 1 to 6 runs a least-privilege SecurityPolicy(default_deny=True) with only the tools the task needs on its allowlist (row 1's argument items go to the guard chain, row 5's G0 tier is contract-only), not the library defaults, under which an empty allowlist allows every tool.

1. 95% CI 96.5–100% (blocked) and 0–3.6% (false-positive); 6 of 10 OWASP ASI slots measured, ASI07–ASI10 are n=0.
2. 0/4 before v0.10.6; 100 policy items admitted and 100 refused on both paths. The 2026-09-16 run's 200/200 policy parity was vacuous: every policy item was refused on both paths (corrected in the results). Isolation-backend execution not run here: no E2B in the runner.
3. AgentDojo v1.2.1 (its CLI defaults to v1.2.2): 524/609 pairs that have a tool-call target, of 949 attacked. Model-in-the-loop ASR 45% → 10% (gpt-4o-mini, 2026-07-31) is one model family on a 60-pair subset, under AgentDojo's fixed-template attack, not an adaptive one. Claude 5.5 (168 pairs/arm, 2026-10-16) is a near-null: Haiku and Sonnet resist unaided (undefended ASR 5-8%), so airlock's realised reduction is +0-1% at a +14% benign-refusal cost; against models this robust the 86% deterministic bound is the informative measure.
4. 1650/1650 API-model calls; G0 contract-only 2.4%; benign-proxy false-refusal 2.4% (G) / 4.1% (LP), over a free judge-free replay of 27 models' recorded calls. Fresh Claude 5.5 two-arm run (2026-10-16) confirms it: Haiku 74/74, Sonnet 42/42, Opus 26/26 direct poisoned calls refused, 0-6% benign cost.

Summary and method: BENCHMARK.md. Every row, with the full results for each: Benchmarks.

Where this sits

The decorator is in-process: not a proxy, a gateway or a sidecar. It runs inside the process that executes the tool, the only place the real Python arguments exist. A gateway authenticates identity and transport and sandboxes the server, but it does not check a tool call's argument contract: live, a Docker MCP Gateway forwarded all 12 malformed payloads that airlock blocks (row 6 above).

Framework support

Both paths use the same @Airlock() decorator. Adapter-shipped means a module in the package handles the framework's glue (signature preservation, tool-registry rewrites, request shapes, approvals); example-only means the plain decorator works.

Adapter-shipped (16) modules for 12 frameworks: LangChain (integrations/langchain.py), LangGraph (integrations/langgraph.py at the ToolNode, integrations/langgraph_toolnode_compat.py), OpenAI Agents SDK (integrations/openai_guardrails.py, integrations/openai_agents.py), Anthropic Messages API (integrations/anthropic.py), Anthropic Claude Agent SDK (integrations/anthropic_claude_agent_sdk.py, v0.6.1+), smolagents (integrations/smolagents_wrapper.py), Gemini 3 Agent Mode (integrations/gemini3_tool_shape_adapter.py), GPT-5.5 (integrations/gpt5_5_tool_shape_adapter.py), PydanticAI (integrations/pydantic_ai.py, integrations/pydantic_ai_approvals.py, v0.7.1+), CrewAI (integrations/crewai.py, v0.7.2+), Google ADK (integrations/google_adk.py, integrations/google_adk_plugin.py, v0.9.0+), FastMCP (agent_airlock/mcp/).

Example-only (2): AutoGen, LlamaIndex — decorator-compatible without an adapter.

Decorator-ordering rules per framework: docs/COMPATIBILITY.md.

Security coverage

Mapped against the OWASP Agentic Top-10 (2026). Partial means airlock covers the runtime leg and something upstream is out of scope. Each row's evidence (guard module, preset, test, measured rate) is in docs/owasp-agentic-2026-coverage.md, which is generated from a YAML source and byte-diffed in CI.

MCP-specific mapping

Against the MCP Top-10. Each row's evidence (modules, presets, tests, where each control runs) is in docs/owasp-mcp-top-10-coverage.md, generated from YAML and byte-diffed in CI.

CLI

One CLI: airlock <command> (since v0.8.56)

airlock scan-tools ./tools.json     # static contract check on tool declarations
airlock doctor                      # scan code for unprotected tools, unsafe patterns
airlock explain --unused-scopes ... # diff granted privilege against used
airlock attest receipt emit ...     # signed evidence that a run was gated
airlock policy compile "..."        # English to typed policy (needs an LLM backend)
airlock kill-switch trigger ...     # HMAC-signed fleet freeze

Per-command pages: docs/cli/.

Performance

How numbers are reported here

This project holds itself to a rule worth stating plainly: a claim in this README is gated by a test, or it is not made.

• Counts — tests, CVEs, adapters — are cross-checked against the tree by tests/test_numeric_claim_parity.py and siblings. A number that drifts fails the build.
• Null results are published. The prompt-injection row above found nothing and says so, in the same table as the wins.
• Competitor numbers are never fabricated. Where an incumbent is cited it is from their published scope and marked not re-run; where a comparison was run live, it says so.
• Where no head-to-head exists, that is recorded rather than implied — see Prior art, including arXiv:2608.18351, where the honest claim is complementarity and not superiority.

Known gaps and their status: ROADMAP.md.

Documentation

Contributing

Read AGENTS.md first — it is the load-bearing contributor contract — then CONTRIBUTING.md.

pip install -e ".[dev]"
make test lint

Every feat: needs a regression test. Every CVE fixture needs a primary-source URL in the commit message. Claims need gates.

Security

Report vulnerabilities via SECURITY.md. Please do not open a public issue for an unpatched vulnerability.

License

Apache-2.0. Relicensed from MIT on 2026-09-06 to add an explicit patent grant. Citation metadata: CITATION.cff.