Repository navigation
feat(oversight): bind approvals to the call they approve - #419
Merged
Merged
Conversation
This was referenced Oct 31, 2026
sattyamjjain
force-pushed
the
fix/fail-closed-verdicts
branch
from
November 1, 2026 04:40
39e03aa to
4b16e04
Compare
OversightRequest carries the sha256 of the call's bound arguments, a masked preview, the agent and session ids, the policy digest and an expiry; a response echoing another digest, or a granted call whose arguments changed while the approver decided, is refused as policy_indeterminate. authorize_once takes args_digest and ttl_seconds, is spent under a lock and shared by with_metadata() clones. SecurityPolicy gains standing_grants (operator-made, exact tool and target arguments, audited, revocable) and an approval_ledger whose SQLite claim runs in BEGIN IMMEDIATE so replicas never both run one approval. Raised in agno-agi/agno#10600 and google/adk-python#7148. Co-Authored-By: Claude Opus 5.5 <[email protected]>
A plain dict such as {"__bytes__": "6869"} was written exactly as b"hi",
and {"__unserializable__": "Session"} as a host Session object. Model
JSON can build those dicts, so a call could reuse another call's
approval digest or match its standing grant. A mapping with a key
shaped like a tag is now written as key-value pairs.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
sattyamjjain
force-pushed
the
feat/bound-approvals
branch
from
November 1, 2026 04:45
1099c0c to
272935e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #410 (
fix/fail-closed-verdicts), since it changes the approval flow #410 rewrote. Retarget tomainafter #410 merges.Summary
An approval now binds to the exact call it approves: these arguments, once, and for a limited time. Until now the approver saw only the escalation's reason and rule (core.py:2747 on b21aec7), so it could not see what it approved, and
authorize_oncewas a set of tool names, checked and then discarded without a lock and copied bywith_metadata().Raised in agno-agi/agno#10600 (approved, then the arguments changed, and the substituted call ran 3 of 3 times), crewAIInc/crewAI#6859, google/adk-python#7148 (an in-memory claim let two replicas both run the call), agentarea/agentarea#650 and openai/openai-agents-python#4896.
OversightRequestgainsargs_digest,args_preview,agent_id,session_id,policy_digestandexpires_at, all with defaults, so a 0.10.28 approver keeps working.args_digestis the sha256 of canonical JSON of the bound arguments (agent_airlock.approvals.args_digest): sorted keys, a non-finite float spelled out, and a{"__unserializable__": type(value).__name__}marker for anything JSON can't encode.args_previewgoes throughAuditLogger._redact_args, andpolicy_digestthrough_compute_policy_digest(), which works on unfrozen policies too.OversightResponsecan echoargs_digest; one that differs from the request's is refused aspolicy_indeterminate. No echo is read as before.authorize_once(tool_name, *, args_digest=None, ttl_seconds=None)is spent under a lock (GrantStore), andwith_metadata()clones share the store instead of copying it. The reauth guard and the action-contradiction gate both spend through it, so a grant bound to args A never admits args B.ApprovalLedger, withInMemoryApprovalLedgerandSQLiteApprovalLedger(theBEGIN IMMEDIATEpattern fromagent_commerce_caps.py).SecurityPolicy(approval_ledger=...)claims a matching approval before asking the approver, atomically, so replicas sharing the file never both run one approval. Expiry isnow >= expires_at.SecurityPolicy.standing_grants: an operator's standing approval of one exact tool with exact target arguments. Only host code makes one, the call's audit record names it (standing_grant),revoke_standing_grant(grant_id)stops it, and an approver'sGRANTnever turns into one.Two refusals I added beyond the list, both on the same theme:
policy_indeterminateand the tool never runs. This is the agno#10600 shape inside one process.policy_indeterminatewithout asking, since no approval can bind to them.@requires_human_oversightfills the same request fields and raisesValueErroron a mismatched echo or arguments changed after the request, the way it already treats a mismatchedrequest_id.Where I went past or around the work order
(tool_name, args_digest), soclaim(tool_name, args_digest, call_id)andgrant(tool_name, args_digest, *, expires_at). The digest covers the arguments only, so keying on it alone would let an approval fortransfer(to=x, amount=5)be claimed by any other tool called with the same arguments.Order(amount=10)would admitOrder(amount=10_000). Models, dataclasses, bytes, sets, non-string keys and non-finite floats are encoded by value. The__unserializable__marker is kept for host objects model JSON can't build, such as a framework's injected context.{"__bytes__": "6869"}was encoded exactly asb"hi", and{"__unserializable__": "Session"}as a hostSessionobject. Model JSON can build those dicts, so a call could reuse another call's approval digest or match its standing grant. A mapping with a key shaped like__x__is now encoded as key-value pairs, which no tag can be. I found it while building the decision record on top of this.freeze()moves the digest, so the frozen policy refuses every call. Revoking one only narrows the policy, so it doesn't, andfreeze()carries revocations over. Otherwise revoking on a frozen policy would refuse every call.SecurityPolicy()andSTRICT_POLICY).reviewercallable, which the work order puts in a separate PR. Ledger approvals don't bind to an agent: any agent making that exact call can claim one.Changed
AirlockContext._authorized_onceis aGrantStore, not aset.instill works, andconsume_grantstill spends a set a duck-typed context carries.SecurityPolicy.check_reauthorizationandActionContradictionGate.check_actiontake an optionalargs_digest.standing_grant. Every other record is unchanged.Test Plan
pytest tests/test_bound_approvals_0_10_29.py: 45 passed in 0.40s. The concurrency tests passed 30 of 30 repeated runs.make lint: ruff check and ruff format clean; mypy shows only the 3 known local errors atintegrations/langchain.py:330(langchain-core 1.6.9 is installed locally, CI doesn't have it)pytest -m "not docker"with--cov=agent_airlock --cov-fail-under=82: 8171 passed, 50 skipped, 5 deselected; coverage 90.10%mkdocs build --strictandscripts/check_docs_api.py: cleanscripts/check_bare_imports.py: all 205 modules import with the installed coreSecurityPolicy()andSTRICT_POLICYidentical to fix(security): refuse indeterminate and late approvals distinctly #410's branchThe new module covers every case the work order lists: a grant for args A doesn't admit B, A admits once and a second A is refused;
asyncio.gatherof two identical calls with one grant runs one; two processes sharing a SQLite ledger, one claim wins; a grant atnow == expires_atis refused; a response echoing another digest is indeterminate; the request carries the digest and a masked preview with no raw secret; a grant spent through awith_metadata()clone is gone from the original.Mutation check
Each mutation runs in its own interpreter over
tests/test_bound_approvals_0_10_29.py(43 pass on the fixed code).now > expires_atwith_metadatacopies the grants (as 0.10.28)BEGIN IMMEDIATE==(True == 1)The SQLite mutation survived at first: the two-process test's children import the unpatched module.
test_two_connections_racing_for_one_approval_one_winsraces two connections in one process, where only SQLite's write lock stands between them, and catches it.CHANGELOG lines owed to the next release (not in this PR)
Added:
agent_airlock.approvals:args_digest,StandingGrant, and theApprovalLedgerprotocol withInMemoryApprovalLedgerandSQLiteApprovalLedger.SecurityPolicy(standing_grants=..., approval_ledger=...)admits an escalated call by an operator's standing grant or by an approval claimed from the ledger (one call per approval, across processes with SQLite) before asking the approver.authorize_oncetakesargs_digestandttl_seconds.Security:
OversightRequestcarriesargs_digest, a maskedargs_preview,agent_id,session_id,policy_digestandexpires_at; a response echoing anotherargs_digest, or a granted call whose arguments changed while the approver decided, is refused aspolicy_indeterminate.authorize_oncegrants are spent under a lock and shared bywith_metadata()clones, which copied them. Raised in fix(agent): reject forged tool continuations and enforce approval gate on /continue agno-agi/agno#10600 and ToolConfirmation deny verdict is never enforced by the framework: custom BaseTool executes after user clicks Decline (adk-python 2.9.1) google/adk-python#7148.Changed:
policy_indeterminatewithout asking the approver.🤖 Generated with Claude Code