|
| 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. |
0 commit comments