Skip to content

Intent grants: approve costly payments once, with limits - #642

Merged
LoopGlitch26 merged 9 commits into
mainfrom
agent/intent-grants-design
Nov 6, 2026
Merged

LoopGlitch26 merged 9 commits into
mainfrom
agent/intent-grants-design

Conversation

@LoopGlitch26

@LoopGlitch26 LoopGlitch26 commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

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 verify re-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

  • From a held call. tracekit approvals show ID prints 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 1h issues 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.
  • Directly. tracekit grant add --run RUN …, tracekit grant list, tracekit grant revoke ID. From code: the signer calls grant_issue, grant_list, grant_revoke (protocol 22).
  • The grant is a PCM grant in PCM's format, unchanged (PCM's spec, schemas and pcm_* calls are untouched). The signer's intent.grant record carries it with its limits (sum of amount, optional count), its totals and the person's note. It lasts 24 h at most, can't be passed on, and covers one run.
  • The decision. Only an ask whose 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: flag with TK-GRANT and ext.grant {id, fields, used, tier}. Outside: ask with the reason, e.g. grant g-…: payee "0x3333…" is not one of "0x1111…", "0x2222…" or grant g-…: 400 of 500 USDC used; this call needs 200 USDC.
  • Who issues. As who answers the run's approvals: with signer.yaml approvals, a named approver who isn't the run's own user; on the dev signer, the run's own user, recorded self_approved and shown so by the verifier. TK-D012 now also denies the agent's own tracekit grant add and approvals approve --grant. grant list and revoke (which only narrows) stay open.
  • Tiers. Releases happen at T1 and T2, and each records its tier: T2 when an executor or gateway decided and ran the call, T1 on the arguments the harness reported. A payment typed into a shell command stays held.
  • Operator ceiling. Optional signer.yaml grants: {payment.send: {ceiling: ["1000 USDC", "500 USD"]}}; a grant over it is refused when issued.
  • Verifiers and viewer. The Python and TypeScript verifiers add an intent grants line, a warning when anything is off (format v2's non-critical ext slot; no closed-schema change). They agree on an honest bundle and on 23 edited-record cases. The viewer marks released payments WITHIN GRANT and lists the run's grants in PERMISSIONS.
  • Totals survive a restart: they are rebuilt from the run's records.

Measured

Result
E23 (new, eval/e23_grants.py) 30 payments: the person's stops fall from 30 to 7, 23 released, 0 outside the limits released; 25 of 25 attack calls held (amounts in other units, hundredths of a USDC past the cap, a currency with no known unit, payee look-alikes, a second payee, a fee, a split, a memo, an invoice or order id, another currency, another tool); 3 of 3 authority tries refused (the agent issuing, passing on, or a grant past a day); 100 payments of 7 USDC under a 50 USDC total: 7 run, 49 spent; revoked and expired grants release nothing; totals kept across a restart; the bundle verifies with its intent grants line
E17 identical to main except the pack's policy hash: deny recall 100%, benign FP 0.11%
E21 robustness and false positives identical to main's committed results (strict: held-out 12.96%, blind 13.68%, the same "over target" lines main has); the committed file changes only the dev and strict packs' hashes. Its latency block stays as on main, which the README and docs/evaluation.md quote and CI doesn't compare; the owner's fresh run measured p99 267 / 312 µs (default, RE2 / regex) against main's recorded 282 / 344
#605's scoreboard (the study week, dev.yaml) identical to main: false stops by rule, 6 of 8 needed stops, 776 of 1,350 attacks through; p99 median of four alternating runs 1.75 ms on both
Tests tests/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.py agreement on 23 cases; full gates below

Run like a user

A throwaway home, the dev signer, a fake MCP payment tool (mcp__payments__send_money) through Claude Code's hook:

[tracekit] HELD, nothing ran: apr-99c7… (TK-A044, TK-F006), expires 07:19 UTC.
Why: moving money through an MCP tool (sending, transferring or converting money, or a refund)
$ tracekit approvals show apr-99c7…
grant       a payment grant reads it as 120 USDC to "0x1111111111111111111111111111111111111111"; to approve it and let more payments like it run, set your own limits:
            tracekit approvals approve apr-99c7… --grant --payee 0x1111… --max '120 USDC' --total '600 USDC' --for 1h

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 last said VERIFIED.

Contract and format

  • Signer RPC: grant_issue, grant_list, grant_revoke, contract version 22 (a signer still serves 15..21 clients).
  • Evidence: no closed-schema change. ext names intent.grant, intent.revoked (records) and grant (on policy.decision), interpreted from verifier 1.6.0.
  • Policy: an ask rule's approval: {grant: payment.send}; TK-GRANT reserved; TK-D012 extended.
  • signer.yaml: grants (optional ceiling).

Security review fixes (independent review of b281e13)

  1. Operator sum limits apply to what a grant releases. The check for a sum limit that can't read a call ran before the grant's release, so a released payment skipped it. It now runs after: such a call is held (TK-LIMIT-SUM) and the grant counts nothing.
  2. Units and tools. amount is the currency's smallest unit and amount_cents hundredths of its whole unit, per a table of known currencies (ISO 4217 exponents; USDC and USDT 6). An unknown currency, both keys, or an amount_cents that isn't a whole number of the smallest unit holds. Each grant names the tools it covers (the held call's, and --tool for grant add); a call of another tool never rides it.
  3. Only free text rides along. Besides amount, currency and payee, a released call may carry only description and note; memo, invoice and order ids, idempotency keys and anything else hold, naming the key (AP2's rule that an unknown constraint fails).
  4. TK-D012 denies every tracekit grant the agent runs, whatever its options and action (list and revoke too), as tracekit, 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 --signer slipped the earlier action pattern). Tested on both engines, a 64 KiB flood of options included. A python -c call of grant_issue stays the documented dev tripwire limit, as for approvals.
  5. The verifier fails a release that breaks its grant (outside caveats or limits, wrong totals, another tool, a non-integer amount, a wrong tier), and one whose grant is missing from the bundle or only in a grant record no signer writes (re-review: a 2099 expiry or a removed caveat with the id recomputed), and a decision flagged TK-GRANT that carries no ext.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

  • A sum limit on a text field passed issue checks and would have crashed every later decide in that run.
  • The Python verifier crashed instead of warning on a malformed grant record.

Stops while building this

Step What stopped it What happened
A lookup of constants (python -c) Tracekit deny (TK-D007) Not redone; read the source
E21 on the branch Tracekit hold (TK-SHELL-PARSE) The owner ran it
The TypeScript port's own by-hand verify of a grants bundle Tracekit deny (TK-D007, TK-F003, TK-F011) Not redone; the agreement test compares both verifiers' lines
The docs edits as a Python script Tracekit deny (TK-D002, TK-D007, TK-F001) The owner ran the script
Issuing a grant in the run-through the person's step (TK-D012) The owner ran it

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.
@LoopGlitch26 LoopGlitch26 changed the title Design: intent grants for costly actions (proposal) Intent grants: approve costly payments once, with limits Nov 6, 2026
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.
@LoopGlitch26
LoopGlitch26 merged commit 894fa06 into main Nov 6, 2026
59 of 60 checks passed
@LoopGlitch26
LoopGlitch26 deleted the agent/intent-grants-design branch November 6, 2026 22:57
LoopGlitch26 added a commit that referenced this pull request Nov 6, 2026
Conflict in tracekit/cli.py: this branch's _claude_code_run and #642's
_grant_hint were added at the same place; both stay. #642's grant command is
in the help groups.
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>
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant