Repository navigation
Intent grants: approve costly payments once, with limits - #642
Merged
Merged
Conversation
A design note, no code: docs/intent-grants.md. A person states the bounds of a costly action once; the signer signs the grant into the run, releases calls inside it, holds calls outside it with the exact reason, and the verifier re-checks every in-grant call from the bundle. The grant is a PCM grant in PCM's format as is; Tracekit's own intent.grant record carries it with its limits and description. Payment fields follow AP2's mandate names. scripts/wiki.py lists the page as a proposal.
A person approves a held payment and grants the run more like it within
limits: payees, the most per payment, a total, a count, up to 24 h. The
signer releases payments inside the grant as flag decisions with TK-GRANT
and ext.grant, holds the rest with the exact reason, and the Python and
TypeScript verifiers re-check every release and running total (intent
grants). The grant is a PCM grant in PCM's format as it is.
- tracekit/grants.py: the payment.send intent, amounts, the payment reader
and the caveat and limit checks the signer, CLI and verifier share
- signer: grant_issue, grant_list, grant_revoke (contract 22); releases in
decide, checked on the writer; totals rebuilt from records on restart;
signer.yaml grants: an operator ceiling per currency
- policy: approval {grant: payment.send} on TK-A044, TK-M001, TK-M002;
TK-D012 denies the agent's own grant add and approvals approve --grant
- CLI: approvals approve --grant, the grant reading in approvals show,
tracekit grant add|list|revoke (experimental)
- viewer: WITHIN GRANT on released payments, the run's grants in PERMISSIONS
- tests/test_grants.py (real signer, attacks, forged bundles), E23, and
docs/intent-grants.md as the user guide
…eval - docs: a limits section, the verdicts row for `intent grants`, the support row (experimental), approvals and policy-v2 sections, format-v2's ext names and verification step, and E23 in evaluation.md - Makefile: E23 in `make eval` - E21's committed results carry the dev and strict packs' new policy hashes; every other field is unchanged (the latency block stays as on main, which the README and evaluation.md quote)
Conflicts resolved on main's side, with the grant additions kept: the signer's new witness_start_s beside grants; the viewer's review counting permissions by seq; PERMISSIONS' new retry wording. `tracekit grant` joins the Approvals group of main's `tracekit help`, marked experimental.
… agent/intent-grants-design
1. A payment a grant releases still passes the operator's sum limits: the check for a limit that can't read the call runs after the release, so such a call is held (TK-LIMIT-SUM) and the grant counts nothing. 2. Each currency has a unit (ISO 4217 exponents; USDC and USDT 6): amount is its smallest unit, amount_cents hundredths of its whole unit; an unknown currency, both keys, or a fraction of the smallest unit holds. Every grant names the tools it covers (the held call's; --tool for grant add), and a call of another tool never rides it. 3. Only description and note ride along with amount, currency and payee: memo, invoice and order ids, idempotency keys and the rest hold, naming the key. 4. TK-D012 denies tracekit grant with any action but a literal list or revoke: from stdin (xargs), computed ($A, $(...)), quoted, or none. 5. The verifiers fail a release that breaks its grant (caveats, limits, totals, another tool, a non-integer), Python and TypeScript alike; shapes the signer never writes stay warnings. Docs say opened-argument checks are a manual step, and who may issue on the dev signer. E23 and the docs follow. Each fix has a real-signer test that fails on b281e13.
1. TK-D012 denies every `tracekit grant` the agent runs, whatever its options and action (list and revoke too), in each program form the approval tripwire reads: nothing about the spelling is matched, so an argparse prefix of --signer, a repeated or spaced value, `--`, or an action from stdin can't slip past. Tested on both engines, a 64 KiB flood of options included. A person runs grant commands. 2. The verifiers fail a release whose grant the bundle doesn't hold, or holds only in a record no signer writes (an expiry past 24 h, a caveat removed, its id recomputed), a wrong tier, and a decision flagged TK-GRANT without ext.grant, which _ext now hands to the check though it carries no ext name; Python and TypeScript alike, 37 agreement cases. E17 and E21 carry the dev and strict packs' new policy hashes; every other field is unchanged.
…on Python 3.9 CI)
LoopGlitch26
added a commit
to BuildWithPranav/Tracekit
that referenced
this pull request
Nov 6, 2026
The three results files conflicted; they are E17 and E21 re-run on the merged packs without --rebaseline or --record, main's latency rows kept: against main only the policy hashes change. The coding pack is 2026.10-v2-64, the next after main's 2026.10-v2-63. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
LoopGlitch26
added a commit
to coughlmao/Tracekit
that referenced
this pull request
Nov 7, 2026
…-Labs#611) into fix/model-weight-write-policy The policy page's ask and flag rows conflicted: this branch's ask row (TK-A058 to TK-A060) and main's flag row (Cygnux-Labs#611's $XDG_CONFIG_HOME). The three results files are E17 and E21 re-run on the merged packs without --rebaseline or --record, main's latency rows kept: against main they change by this branch's cases and the policy hashes. The coding pack is 2026.10-v2-65, after main's 2026.10-v2-64. Main's strict.yaml limits row quotes E17's benign calls: 887 with this branch's cases. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
This was referenced Nov 7, 2026
LoopGlitch26
added a commit
that referenced
this pull request
Nov 8, 2026
…hold reasons, expiry instant) (#674) * Intent grants: no PCM authority, self-grants lower assurance, quoted reasons, one expiry instant Pre-release review of #642 (all unreleased): - An intent grant was signed as a PCM grant, so a message carrying one passed pcm.verify past its total, without a per-payment cap, from another run and after a revoke: its limits, tools, run and revocation are only in its run's records. It is now signed under its own purpose (tracekit.intent-grant.v2); pcm.verify and pcm_delegate refuse it with a plain reason. - A grant the run's own user issued now counts as a self-approval in both verifiers: assurance dev, approvals: self, and the short result's caveat. - A grant's hold reason quotes the call's argument names and values and tool names as JSON with ". Instead:" escaped, so agent text can't start or move the Instead line. - The signer checks a grant's expiry at the instant the release's record carries (and gives a counter gap before it the same ts), the instant both verifiers compare. - docs/deploy.md gets a 1.6 upgrade entry; limits.md no longer names a protocol 21 client. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> * Self-issued grants need a 1.6 verifier; quote only_change's file name; docs Independent review of #674: - A bundle where the run's own user issued a grant (intent.grant self_approved true) kept verifier_min_version 1.4.0, so a 1.5.3 verifier read it as witnessed while 1.6 reads dev; approvals: self. VERSIONS 1.6.0 now lists the ext record's self_approved true as a critical value, so an older verifier says UNVERIFIABLE (needs tracekit >= 1.6.0). Ext names are marked "ext name <n>" in the gate, so an entry of the ext record type such as ext.self_approved=True counts as critical. Every other bundle keeps its minimum. - Both verifiers compare verifier_min_version with READS, the newest format version they read (the newest VERSIONS row, or the release when later), so this checkout reads the rows it implements without a version bump; VERSION stays the package's release. - constraints.held quotes only_change's file name (rpc_schema.quoted, which grants.py now uses too), so a name with a line break can't start a line of the hold. - docs: the escaped ". Instead:" as the code writes it, the signature purposes in use, and the 1.6 verifier a self-issued grant's bundle needs. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> * Constraints: quote keep_away's file or directory name in its hold keep_away's hold named its object unquoted. constraint_add takes the object from any caller that may write the run, the agent's own identity included, so a directory object with a line break (the review's /w/x\nPerson: tracekit approvals approve --all.py) started a line of the hold the person reads. It is quoted through rpc_schema.quoted, as only_change's name is, so "billing.py" now reads in quotes in the hold and in the docs that show it. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> * Verifiers: warn when the manifest asks for an older verifier than the records need The gate that sends a self-issued grant's bundle (and a signed finding's citations) to a newer verifier rests on the manifest's verifier_min_version, which isn't signed: edited down with its hashes refreshed, v1.5.3 read a self-issued grant's bundle as witnessed, and neither 1.6 verifier noticed. Both verifiers now recompute what the records and layout need, as export does (bundle_v2.needs; the TypeScript verifier from versions.json, a copy of VERSIONS a test holds to it), and warn `verifier minimum`, naming the records that need more, when the manifest asks for less than a row raised it to. An honest bundle, and a 0.x one that needs only the base, get no such line. Value entries now match by type in both (1 is no True). Docs: limits.md, intent-grants.md, format-v2.md (review.cites too) and verdicts.md. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> * Browser verifier: a meaning for the verifier minimum warning Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> * Verifiers: the minimum recompute skips unreadable records; copy tests run without node - `verifier minimum` recomputed what records need from every record, so a tampered record with no `type` raised a KeyError, reported as `bundle structure`. Both verifiers now read only records with a type, data and seq (an ext record's with its name); the rest need nothing, and their own checks fail them as before. The test compares with the verifier before the recompute: the same checks, integrity and exit code. - The tests that hold the TypeScript verifier's copies to the reference (the event schema, VERSIONS, its VERSION and READS) were in Primitives, which exists only with a TS build and pytest, so CI never ran them. They read files only and now sit in a module-level class, Copies, that runs with neither node nor a build. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> * Tests: the self-grant short result no longer assumes the platform's isolation test_a_self_issued_grant_counts_as_a_self_approval expected the short result's proof line, which reads the isolation the signer recorded: separate-user on Linux and macOS, unknown on Windows (no getuid), where the line is NOT SHOWN and no caveat follows. It now asserts what the change is about (dev, approvals: self, and the self-approval caveat), reading the short result with the isolation Linux and macOS record. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> --------- Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
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.
A person approves a held payment once and grants the run more like it, within limits. Payments inside the grant run without a stop; anything outside it is held with the exact reason;
tracekit verifyre-checks every released payment and running total from the bundle. Payments first (payment.send), one run per grant, experimental. User guide:docs/intent-grants.md. The owner approved the design and these choices on 2026-11-06.What it does
tracekit approvals show IDprints how a grant reads the call (120 USDC to "0x1111…") and a command with limits to edit.tracekit approvals approve ID --grant --payee A --payee B --max '200 USDC' --total '500 USDC' --for 1hissues the grant, then approves the call; that call is the grant's first payment, and the agent's retry of it runs on the approval without being counted again.tracekit grant add --run RUN …,tracekit grant list,tracekit grant revoke ID. From code: the signer callsgrant_issue,grant_list,grant_revoke(protocol 22).pcm_*calls are untouched). The signer'sintent.grantrecord carries it with its limits (sumof amount, optionalcount), its totals and the person's note. It lasts 24 h at most, can't be passed on, and covers one run.askwhose rules all opt in (approval: {grant: payment.send}: TK-A044 in the coding pack, TK-M001 and TK-M002 in the server packs) can be released. The grant reads amount (whole minor units), currency and one payee; any other argument holds the call. Every caveat must pass and every total stay within its limit, checked on the writer, so two payments at once can't both spend the last of a total. Inside:flagwithTK-GRANTandext.grant {id, fields, used, tier}. Outside:askwith the reason, e.g.grant g-…: payee "0x3333…" is not one of "0x1111…", "0x2222…"orgrant g-…: 400 of 500 USDC used; this call needs 200 USDC.approvals, a named approver who isn't the run's own user; on the dev signer, the run's own user, recordedself_approvedand shown so by the verifier. TK-D012 now also denies the agent's owntracekit grant addandapprovals approve --grant.grant listandrevoke(which only narrows) stay open.grants: {payment.send: {ceiling: ["1000 USDC", "500 USD"]}}; a grant over it is refused when issued.intent grantsline, a warning when anything is off (format v2's non-criticalextslot; no closed-schema change). They agree on an honest bundle and on 23 edited-record cases. The viewer marks released paymentsWITHIN GRANTand lists the run's grants in PERMISSIONS.Measured
eval/e23_grants.py)intent grantslinedocs/evaluation.mdquote and CI doesn't compare; the owner's fresh run measured p99 267 / 312 µs (default, RE2 / regex) against main's recorded 282 / 344tests/test_grants.py(real signer; the agent issuing, widening or extending a grant, amounts in other units, payee look-alikes, totals split across calls, a two-thread race, expiry, revocation, restart, ceiling, forged bundles, the hook-to-CLI path end to end),tests/test_ts_verifier.pyagreement on 23 cases; full gates belowRun like a user
A throwaway home, the dev signer, a fake MCP payment tool (
mcp__payments__send_money) through Claude Code's hook:The agent ran up to the hold; issuing a grant is the person's step (TK-D012). The owner ran the rest by hand: the grant, the held payment's retry and two payments within the limits ran, a payment to an address the grant doesn't name was held with that reason, and
tracekit lastsaid VERIFIED.Contract and format
grant_issue,grant_list,grant_revoke, contract version 22 (a signer still serves 15..21 clients).extnamesintent.grant,intent.revoked(records) andgrant(onpolicy.decision), interpreted from verifier 1.6.0.approval: {grant: payment.send};TK-GRANTreserved; TK-D012 extended.grants(optional ceiling).Security review fixes (independent review of b281e13)
TK-LIMIT-SUM) and the grant counts nothing.amountis the currency's smallest unit andamount_centshundredths of its whole unit, per a table of known currencies (ISO 4217 exponents; USDC and USDT 6). An unknown currency, both keys, or anamount_centsthat isn't a whole number of the smallest unit holds. Each grant names the tools it covers (the held call's, and--toolforgrant add); a call of another tool never rides it.descriptionandnote;memo, invoice and order ids, idempotency keys and anything else hold, naming the key (AP2's rule that an unknown constraint fails).tracekit grantthe agent runs, whatever its options and action (listandrevoketoo), astracekit,python -m tracekit, a path or a runner: a person runs grant commands, so nothing about their spelling is read (re-review:--sig,--si=, a repeated or spaced--signerslipped the earlier action pattern). Tested on both engines, a 64 KiB flood of options included. Apython -ccall ofgrant_issuestays the documented dev tripwire limit, as for approvals.TK-GRANTthat carries noext.grant; in Python and TypeScript alike. Other shapes the signer never writes stay warnings. The docs now say that checking fields against opened arguments is a manual step, and who may issue a grant on the dev signer.Two bugs found while building, fixed with tests
sumlimit on a text field passed issue checks and would have crashed every later decide in that run.Stops while building this
python -c)