Skip to content

Commit 1055c15

Browse files
sattyamjjainclaude
andcommitted
feat(oversight): bind approvals to the call they approve
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]>
1 parent 1a6d930 commit 1055c15

12 files changed

Lines changed: 1672 additions & 70 deletions

File tree

‎docs/api/policy.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ class SecurityPolicy:
3434
approver: Approver | None = None
3535
escalation_channel: str = "default"
3636
escalation_timeout_seconds: float = 300.0
37+
standing_grants: list[StandingGrant] = field(default_factory=list)
38+
approval_ledger: ApprovalLedger | None = None
3739

3840
# Budgets and guards, all off by default
3941
model_tier_budget: ModelTierBudget | None = None
@@ -62,6 +64,8 @@ class SecurityPolicy:
6264
| `capability_policy` | `CapabilityPolicy \| None` | Checked against what a tool declares with `@requires(...)` |
6365
| `escalate_tools` | `dict[str, str]` | Tool patterns that need a human's approval, with the reason the approver sees |
6466
| `approver` | `Approver \| None` | Transport that asks the human. A matched escalation with no approver is refused. It runs in a worker thread and must answer within `escalation_timeout_seconds` (default 300): no answer in time is refused as `escalation_timeout`, and a later answer is dropped, so an approver must not act after its deadline. An answer that is not an `OversightResponse` with an `OversightVerdict` verdict (the string `"grant"`, `None`, an exception) is refused as `policy_indeterminate`. On an async tool the event loop keeps running while it decides, and an `async` approver is awaited |
67+
| `standing_grants` | `list[StandingGrant]` | The operator's standing approvals of one exact tool called with exact target arguments: such a call runs without asking, and its audit record names the grant. Revoke one with `revoke_standing_grant(grant_id)` |
68+
| `approval_ledger` | `ApprovalLedger \| None` | Approvals recorded ahead of a call, each claimed by exactly one call, before the approver is asked. See [Approvals bound to the call](../guide/bound-approvals.md) |
6569
| `model_tier_budget` | `ModelTierBudget \| None` | Per-model-tier cost caps, checked before the tool runs |
6670
| `amplification_budget` | `AmplificationBudget \| None` | Per-run call budget against a declared baseline |
6771
| `sequence_guard`, `action_contradiction_gate`, `deserialization_guard` | | Optional guards run after the policy check |

‎docs/guide/bound-approvals.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Approvals bound to the call
2+
3+
Since 0.10.29 an approval binds to the exact call it approves: the arguments, once, and
4+
for a limited time. Until then an approver saw only the escalation's reason and rule, and
5+
an `authorize_once` grant admitted the next call of its tool whatever its arguments.
6+
7+
## What the approver sees
8+
9+
An escalated call (`SecurityPolicy.escalate_tools`) asks `policy.approver` with an
10+
`OversightRequest` that now carries:
11+
12+
| Field | What it is |
13+
| --- | --- |
14+
| `args_digest` | sha256 of the call's bound arguments in canonical JSON (`agent_airlock.approvals.args_digest`) |
15+
| `args_preview` | the arguments by name, masked like an audit preview: a value under a secret-sounding name is `[REDACTED]`, personal data and keys are masked |
16+
| `agent_id`, `session_id` | the call's identity, when it carries one |
17+
| `policy_digest` | the digest of the policy that escalated, frozen or not, so a stored decision can be checked against the policy in force on resume |
18+
| `expires_at` | `requested_at` plus `escalation_timeout_seconds` |
19+
20+
The fields have defaults, so an approver written for 0.10.28 keeps working.
21+
22+
To bind its decision, the approver echoes the digest:
23+
24+
```python
25+
from agent_airlock.oversight import OversightRequest, OversightResponse, OversightVerdict
26+
27+
28+
def approver(request: OversightRequest) -> OversightResponse:
29+
ok = ask_a_human(request.tool_name, request.args_preview)
30+
return OversightResponse(
31+
request_id=request.request_id,
32+
verdict=OversightVerdict.GRANT if ok else OversightVerdict.DENY,
33+
args_digest=request.args_digest,
34+
)
35+
```
36+
37+
A response that echoes another digest is refused as `policy_indeterminate`. A response
38+
with no `args_digest` is read as before.
39+
40+
Two more refusals close the gap between the decision and the call:
41+
42+
- If the call's arguments change while the approver decides (a shared dict another task
43+
edits), the call is refused as `policy_indeterminate`: the digest is worked out again
44+
just before the tool runs.
45+
- If the arguments cannot be read (nested deeper than 32 levels, or containing
46+
themselves), the call is refused as `policy_indeterminate` without asking anyone,
47+
since no approval can be bound to them.
48+
49+
`@requires_human_oversight` fills the same fields, and raises `ValueError` on a decision
50+
about other arguments or arguments changed after the approval was asked.
51+
52+
## One-shot grants
53+
54+
`AirlockContext.authorize_once`, which re-opens the reauthorization guard and a tripped
55+
action-contradiction gate, can name the call it admits and a time to live:
56+
57+
```python
58+
from agent_airlock.approvals import args_digest
59+
60+
run.authorize_once("pay", args_digest=args_digest({"to": "bob", "amount": 10}))
61+
run.authorize_once("pay", ttl_seconds=60)
62+
```
63+
64+
A bound grant admits only a call whose arguments hash to it, positional or keyword. A
65+
grant is spent under a lock, so two concurrent calls never both spend it, and a grant is
66+
expired at `now >= expires_at`. `with_metadata()` clones share the run's grants, so a
67+
grant spent through a clone is spent. A grant naming no digest admits one call of its
68+
tool, as before.
69+
70+
## Approvals recorded ahead of the call
71+
72+
`SecurityPolicy(approval_ledger=...)` takes approvals recorded before the call, for
73+
example by a human approving in a dashboard, and lets exactly one call spend each one:
74+
75+
```python
76+
import time
77+
78+
from agent_airlock import SecurityPolicy
79+
from agent_airlock.approvals import SQLiteApprovalLedger, args_digest
80+
81+
ledger = SQLiteApprovalLedger("approvals.db")
82+
ledger.grant("pay", args_digest({"to": "bob", "amount": 10}), expires_at=time.time() + 300)
83+
84+
policy = SecurityPolicy(
85+
escalate_tools={"pay": "moves money"},
86+
approver=approver,
87+
approval_ledger=ledger,
88+
)
89+
```
90+
91+
An escalated call claims a matching approval before asking the approver. The claim is
92+
atomic: `SQLiteApprovalLedger` runs it in a `BEGIN IMMEDIATE` transaction, so replicas
93+
sharing the file never both run one approval. `InMemoryApprovalLedger` does the same
94+
within one process. An approval is expired at `now >= expires_at`, and a ledger that
95+
raises claims nothing, so the approver is asked.
96+
97+
## Standing grants
98+
99+
An operator can approve one tool called with exact target arguments for good:
100+
101+
```python
102+
from agent_airlock import SecurityPolicy
103+
from agent_airlock.approvals import StandingGrant
104+
105+
payroll = StandingGrant(tool="pay", arguments={"to": "payroll"})
106+
policy = SecurityPolicy(
107+
escalate_tools={"pay": "moves money"},
108+
approver=approver,
109+
standing_grants=[payroll],
110+
)
111+
```
112+
113+
- The tool name is exact (a glob is refused) and at least one target argument is named.
114+
Values compare as the digest encodes them, so `1` is not `True` or `1.0`.
115+
- Only host code makes one. An approver's `GRANT` or an `authorize_once` never turns into
116+
a standing grant.
117+
- The call's audit record names the grant (`standing_grant`).
118+
- `policy.revoke_standing_grant(payroll.grant_id)` stops it from the next call on.
119+
- Adding a grant after `freeze()` moves the digest, so a frozen policy refuses every call.
120+
A revocation only narrows the policy, so it does not, and `freeze()` keeps it.
121+
- A denied tool stays denied: escalation, and so a standing grant, is checked last.
122+
123+
## What this does not do
124+
125+
- A ledger approval binds to the tool and the digest, not to an agent: any agent making
126+
that exact call can claim it.
127+
- There is no reviewer step that auto-approves below a threshold.
128+
- The digest reads a host object that model JSON cannot build (a framework's injected
129+
context) as its type alone, so two such objects of one type share a digest.

‎docs/policies/human-oversight-decorator.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,13 @@ class OversightRequest:
105105
channel: str
106106
timeout_seconds: float
107107
requested_at: str # ISO 8601 UTC
108+
# 0.10.29, with defaults:
109+
args_digest: str | None = None # sha256 of the bound arguments
110+
args_preview: Mapping[str, str] = {} # the arguments, masked
111+
agent_id: str | None = None
112+
session_id: str | None = None
113+
policy_digest: str | None = None # @Airlock escalations only
114+
expires_at: str | None = None # requested_at + timeout
108115

109116

110117
@dataclass(frozen=True)
@@ -113,8 +120,13 @@ class OversightResponse:
113120
verdict: OversightVerdict
114121
detail: str = ""
115122
approver: str | None = None # human identifier, optional
123+
args_digest: str | None = None # 0.10.29: echo to bind the decision
116124
```
117125

126+
A response echoing an `args_digest` other than the request's raises `ValueError`, and
127+
so does a `GRANT` for a call whose arguments changed after the request was built. See
128+
[Approvals bound to the call](../guide/bound-approvals.md).
129+
118130
## Testing helper
119131

120132
`InProcessRecordedApprover` returns pre-set verdicts per tool name;

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ nav:
9090
- Token audience & startup hooks: guide/token-audience-and-startup-hooks.md
9191
- Shell & installer arguments: guide/shell-and-installer-arguments.md
9292
- Dispatch arguments: guide/dispatch-arguments.md
93+
- Approvals bound to the call: guide/bound-approvals.md
9394
- API Reference:
9495
- Airlock Decorator: api/airlock.md
9596
- Configuration: api/config.md

‎src/agent_airlock/action_contradiction_gate.py‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@
7878
from typing import Any, Literal
7979

8080
from ._log import structlog
81+
from .approvals import consume_grant
8182
from .policy import PolicyViolation, ViolationType
8283

8384
logger = structlog.get_logger("agent-airlock.action_contradiction_gate")
@@ -290,6 +291,7 @@ def check_action(
290291
context: Any,
291292
tool_name: str,
292293
session_key: str,
294+
args_digest: str | None = None,
293295
) -> None:
294296
"""Run all configured detectors against the context; if any
295297
trips and the tool is a privileged sink, enforce the gate.
@@ -303,6 +305,9 @@ def check_action(
303305
caller derives it from
304306
``context.agent_id``/``session_id`` per
305307
:attr:`session_key_kind` to keep this method pure.
308+
args_digest: The call's :func:`~agent_airlock.approvals.args_digest`,
309+
which an ``authorize_once`` grant bound to arguments must match
310+
(0.10.29).
306311
307312
Raises:
308313
ActionContradictionViolation: ``action="block"`` and the
@@ -327,12 +332,10 @@ def check_action(
327332
if not self._is_privileged_sink(tool_name):
328333
return
329334

330-
# Privileged sink + tripped session → check the one-shot grant.
331-
authorized: set[str] = getattr(context, "_authorized_once", set())
332-
if tool_name in authorized:
333-
# Consume the grant; do NOT clear the sticky flag — the
334-
# next privileged call must mint a fresh authorize_once.
335-
authorized.discard(tool_name)
335+
# Privileged sink + tripped session → spend the one-shot grant, under its
336+
# store's lock (0.10.29). Do NOT clear the sticky flag — the next privileged
337+
# call must mint a fresh authorize_once.
338+
if consume_grant(context, tool_name, args_digest):
336339
logger.info(
337340
"action_contradiction_gate.authorize_once_consumed",
338341
tool_name=tool_name,

0 commit comments

Comments
 (0)