<!-- Canonical: https://lucioduran.com/projects/agent-tool-capabilities
Language: en
Content-SHA256: fa8aa56fb1a788327b91df83fb2881b8ba51eb8b67f7ec6e741fc5f2cb81d10a
-->

[Projects](<https://lucioduran.com/projects>) / Agent Tool Capabilities

# Agent Tool Capabilities

Tool authorization by argument, resource, expiry and atomic call and byte budgets, with verifiable denial and revocation records.

Author: [Lucio Durán](<https://lucioduran.com/>) · Python 3.11.13 · License: [MIT](<https://github.com/lucioduran/agent-tool-capabilities/blob/f4d3df5ea1399da44f6eb90050933b32d3782918/LICENSE>)

Page published: 2026-11-09 · Page updated: 2026-11-09

[Repository](<https://github.com/lucioduran/agent-tool-capabilities>) · [Original evidence](<https://raw.githubusercontent.com/lucioduran/agent-tool-capabilities/f4d3df5ea1399da44f6eb90050933b32d3782918/results/reference.json>) · [Release v1.0.0](<https://github.com/lucioduran/agent-tool-capabilities/releases/tag/v1.0.0>)

## Problem and relevance to agents

A tool name does not constrain its arguments, resource access or cost. Concurrent requests can overspend a budget unless authorization is enforced before effects.

An agent receives only execution authority while a trusted host retains issuance, revocation and tool registration.

## Architecture

1. **Issue bounded grants.** Opaque process-local bearer tokens refer to immutable tool, argument, virtual-resource and expiry scopes.
2. **Reserve atomically.** A shared admission lock validates scope and revocation and reserves both call and input-byte budgets before a callback executes.
3. **Record decisions.** Immutable ordered records omit tokens and argument values. Denials leave the synthetic note store unchanged.

- [Design and trust boundaries](<https://github.com/lucioduran/agent-tool-capabilities/blob/f4d3df5ea1399da44f6eb90050933b32d3782918/docs/design.md>)

## What this demonstrates

- Atomic budget checks under two eight-thread races.
- Strict argument constraints and resource canonicalization before callbacks.
- Revocation ordering with explicit treatment of already admitted work.

## Published results

The local fixed experiment contains 25 sequential cases, two 64-attempt races and an event-controlled in-flight revocation.

Sequential cases replay against owned in-memory note tools. Concurrency evidence records admissions, denials and resource effects; the verifier checks arithmetic without reproducing the historical schedule.

### Admission and revocation checks

| Check | Observed result |
| --- | --- |
| Permitted sequential controls | 3/3 admitted |
| Adversarial or exhausted cases | 22/22 denied |
| Denied calls changing the store | 0/22 |
| Call-budget race, 64 attempts | 7 admitted, 57 denied |
| Byte-budget race, 64 attempts | 7 admitted, 57 denied |
| Revocation | Admitted call finished; subsequent call denied |

The experiment confirms these synthetic cases, not general attack resistance. It makes no throughput, latency or independent security-audit claim.

## Reproduce

Python 3.11 or newer, with no runtime dependencies.

Run measurements in a new destination and serialize heavy workloads. Within the original project series, use the shared benchmark\_lock.py wrapper. Commands below use POSIX shell syntax.

### Verify saved evidence

```
git clone https://github.com/lucioduran/agent-tool-capabilities.git
cd agent-tool-capabilities
git checkout f4d3df5ea1399da44f6eb90050933b32d3782918
python -m experiments.verify results/reference.json
```

### Repeat the local experiment

```
python -m experiments.reproduce --output build/new-run.json
python -m experiments.verify build/new-run.json
```

## Scope and limitations

- Arbitrary Python in the broker process can bypass this application authorization boundary. It is not an operating-system sandbox.
- Bearer-token theft transfers remaining authority. Grants are process-local, without authentication, persistence or distributed enforcement.
- Virtual resource paths do not enforce filesystem symlink, URL redirect or operating-system boundaries.
- Revocation does not cancel admitted calls. Failures consume budgets and may leave partial effects. Audit records are in memory, unbounded and unsigned.

- [Related architecture article](<https://lucioduran.com/blog/capability-based-security-wasi-preview2>)

## Sources and revision

The timestamp, clean implementation revision, source hashes and hardware are recorded in the reference report. The release adds publication artifacts; hashes establish consistency rather than authenticity.

- Reviewed revision: [` f4d3df5ea1399da44f6eb90050933b32d3782918 `](<https://github.com/lucioduran/agent-tool-capabilities/commit/f4d3df5ea1399da44f6eb90050933b32d3782918>)
- Revision recorded by the experiment: [` 7397b9c40f0f284c108f584966b8d6c803ebebcd `](<https://github.com/lucioduran/agent-tool-capabilities/commit/7397b9c40f0f284c108f584966b8d6c803ebebcd>)
- Report timestamp (UTC): 2026-11-09T18:28:21.140506+00:00
- Release published: [v1.0.0](<https://github.com/lucioduran/agent-tool-capabilities/releases/tag/v1.0.0>) · 2026-11-09T18:31:17Z

- [README and usage](<https://github.com/lucioduran/agent-tool-capabilities/blob/f4d3df5ea1399da44f6eb90050933b32d3782918/README.md>)
- [Original evidence](<https://raw.githubusercontent.com/lucioduran/agent-tool-capabilities/f4d3df5ea1399da44f6eb90050933b32d3782918/results/reference.json>)
- [MIT license](<https://github.com/lucioduran/agent-tool-capabilities/blob/f4d3df5ea1399da44f6eb90050933b32d3782918/LICENSE>)
- [Design and trust boundaries](<https://github.com/lucioduran/agent-tool-capabilities/blob/f4d3df5ea1399da44f6eb90050933b32d3782918/docs/design.md>)
- [Measurement methodology](<https://github.com/lucioduran/agent-tool-capabilities/blob/f4d3df5ea1399da44f6eb90050933b32d3782918/docs/evidence.md>)
- [Recorded test coverage](<https://github.com/lucioduran/agent-tool-capabilities/blob/f4d3df5ea1399da44f6eb90050933b32d3782918/results/coverage.txt>)