Metadata-Version: 2.5
Name: agentmandate
Version: 0.31.0
Summary: Compound-path and cross-release analysis of what an AI agent is permitted to do
Project-URL: Homepage, https://github.com/mrwersa/agentmandate
Project-URL: Repository, https://github.com/mrwersa/agentmandate
Project-URL: Issues, https://github.com/mrwersa/agentmandate/issues
Project-URL: Changelog, https://github.com/mrwersa/agentmandate/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/mrwersa/agentmandate#documentation
Author: Saeed Aghaee
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-security,ai-agents,authorization,governance,least-privilege,llm,policy-analysis,reachability,separation-of-duties
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6; extra == 'yaml'
Description-Content-Type: text/markdown

# AgentMandate

> **What is your AI agent actually allowed to do?**

[![PyPI](https://img.shields.io/pypi/v/agentmandate.svg)](https://pypi.org/project/agentmandate/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%20--%203.14-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/mrwersa/agentmandate/actions/workflows/ci.yml/badge.svg)](https://github.com/mrwersa/agentmandate/actions/workflows/ci.yml)
[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](#development)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](https://github.com/mrwersa/agentmandate/blob/main/LICENSE)

AgentMandate is a design-time authority analyser for agentic AI systems. An AI
agent is a goal-directed system, usually built around a language model, whose
runtime supplies tools, identity, memory, policy, and the ability to cause
effects. Those tools may each look safe on their own. AgentMandate finds the
limits the agent can exceed by **combining** individually permitted calls, and
tells you when a release widened what it can reach.

A **mandate** is the reviewed, bounded unit of work the agent is allowed to
carry out while its issuer may be absent. The manifest is the repository's
machine-readable description of that mandate. AgentMandate analyses authority,
not whether the model is likely to choose a particular path.

Alpha. Apache-2.0.

## Run the example

The examples live in this repository. Clone it and install into a virtual
environment (Python 3.10 or newer):

```bash
git clone https://github.com/mrwersa/agentmandate.git
cd agentmandate
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[yaml]"
```

For use in your own project, install `agentmandate[yaml]` from PyPI instead;
the examples below assume you are in the repository root.

A payment-dispute agent has one reviewed mandate. Refunds are capped at 500 GBP
per case, every refund needs human approval, and the mandate may move 500 GBP in
total. It passes:

```console
$ mandate lint examples/dispute-resolver.yaml
no single-manifest findings
```

The next release adds one tool. Read-only, moves no money, changes nothing:

```yaml
  - name: search_cases
    effect: read
    produces: case
    unbounded: true
```

Nobody blocks that in review. It still passes `lint`, because no single tool is
wrong:

```console
$ mandate reach examples/dispute-resolver-v2.yaml
BREACH  cumulative value 1000 GBP exceeds limit 500 GBP
  1. open_case(case#1)
  2. search_cases(case#2)
  3. issue_refund(case#1, 500 GBP)
  4. issue_refund(case#2, 500 GBP)
```

The cap is measured **per case**. The new tool hands the agent cases it did not
open, and there is no fixed number of them, so a per-case ceiling stops
bounding the mandate. Four individually permitted calls, both refunds approved
by a human, 1,000 GBP reachable.

![A read-only case search makes two approved refunds reachable and breaches the mandate-wide limit](https://raw.githubusercontent.com/mrwersa/agentmandate/main/docs/assets/authority-path.svg)

## Why a config diff is not an authority diff

That change is one read-only tool in a pull request. Here is what it did to the
agent's effective authority:

```console
$ mandate diff examples/dispute-resolver.yaml examples/dispute-resolver-v2.yaml
authority diff  v1 -> v2
  + tool: gained search_cases
  + extractable value: 500 -> 2000 GBP
  + reachable breach: gained cumulative_value

verdict: WIDENING
a widening change needs named review before release
```

Exit code 1. A pull request shows what somebody typed. It does not show what
the agent can now do, because reachability composes and text does not. Adding a
read tool or removing a required scope can each
open a path that did not exist, and none of them look like a permission change.

Review the configuration change together with the reachable behavior it enables.

## Put it in CI

```yaml
- uses: mrwersa/agentmandate@v0.26.1
  with:
    manifest: mandate.yaml
    baseline: mandate-released.yaml   # optional: did this widen authority?
    source: src/agent                 # optional: has the manifest drifted?
```

Only the checks you give inputs for run, so a manifest alone is enough to
start. The counterexample renders in the job summary as a graph, and
`sarif-file` is an output you hand to `github/codeql-action/upload-sarif` so it
annotates the diff. `fail-on: never` reports without blocking, which is how to
turn this on over an existing repository without stopping everyone on day one.

The [CI guide](docs/ci.md) covers SARIF uploads and named review decisions from
a protected Git ref. Recorded acceptance retains widening findings; reachable
breaches still block the gate.

**See the whole thing working:**
[agent-release-gate](https://github.com/mrwersa/agent-release-gate) takes one
agent from Python source to a gate decision. Seven checks, one exit code,
offline.

## Adopt it in one repository

1. Start with one agent and one bounded task. Write a manifest, or generate a
   skeleton with `scan` and review every `REVIEW` field.
2. Run `lint` for individual control gaps and `reach` for combinations of calls
   that exceed a limit. Inspect the counterexample and the search depth.
3. Commit the reviewed manifest. Use `diff` against the previous reviewed
   version and `drift` against source in each pull request.
4. Add `verify` when you have recorded calls with the fields your controls
   require. It checks those observations against the declaration.

A clean bounded search is evidence about the declared model. Runtime policy,
identity, approvals, and accounting still need enforcement in the deployment.
AgentMandate runs offline; it does not intercept requests.

The [documentation map](docs/README.md) routes you to the relevant guide.
The dated [landscape survey](docs/agentic-ai-landscape.md) explains the broader
relationship to policy engines, scanners, and evaluation tools.

## Starting from an existing agent

You do not have to write the first manifest by hand. From agent code:

```console
$ mandate scan --source src/agent --agent dispute-resolver > mandate.yaml
```

That reads `@tool`, `@function_tool`, and `@ai_function` declarations and the
`tools=[...]` list they are passed to. It is a static read: nothing is
imported, nothing is executed, and the framework need not be installed.

One manifest describes one agent, so a source building two of them is refused
until you name the one you mean with `--binding`. A union would let `reach`
compose a path across tools that never share a run. What the read could not
enumerate is reported rather than dropped, because a tool missing from today's
manifest shows up in tomorrow's diff as authority that was never added. See
[docs/inventory.md](docs/inventory.md).

Or from an MCP catalogue:

```console
$ mandate scan examples/mcp-tools.json --agent dispute-resolver > mandate.yaml
```

The skeleton is loadable straight away, and every judgement the catalogue could
not supply is marked:

```yaml
  - name: issue_refund
    # REVIEW: effect guessed from the name. read | write | irreversible
    effect: irreversible
    # REVIEW: does this spend the caller's authority or a service account?
    principal: caller
    requires: [case]
    # REVIEW: amount looks like a value argument. A ceiling needs scope_key too.
    # value_arg: amount
    # scope_key: case
    # ceiling: { amount: 0, currency: GBP }
    requires_approval: true
```

Unrecognised verbs are proposed as `irreversible`, because under-calling an
effect is the more expensive mistake.

Use `scan --format mcp|openapi|a2a` for strict local JSON imports. OpenAPI
operations remain adapter candidates; an A2A card requires one explicit
`--dispatch-tool` and its advertised skills are not separate callable tools.
`inventory import` can also write an unreviewed declaration or its inventory IR.
The [catalogue import guide](docs/catalogue-import.md) has runnable examples
and explains the review needed before either output can inform a gate.

## Keeping the manifest honest

A manifest is a reviewed claim about one mandate. Two things quietly falsify
it: somebody adds a tool to the agent and nobody edits the YAML, or a signature
changes and the argument a ceiling was counted against stops existing.

```console
$ mandate drift mandate.yaml --source src/agent
  UNDECLARED  issue_credit_note
      the agent is given this tool and the mandate does not declare it, so
      every reach and diff run so far analysed a smaller graph than the real one

  ARGUMENT    issue_refund
      value_arg names 'amount', which is not an argument this tool takes any
      more (it takes: case_id, total, currency). A ceiling counted against an
      argument that does not exist is not a ceiling.

  REMOVED     close_case
      the mandate declares this tool and the agent is not given it in source,
      so the analysis is defending authority nobody has.
```

The argument finding exposes a stale control: the manifest still parses, but
its value argument no longer matches the implementation.

A tool list the read cannot enumerate, such as `tools=load_tools()`, is itself
a finding. Reporting no drift from evidence that could not see the whole list
would be the false assurance this package exists to prevent.
Reviewed dynamic inventories can discharge that uncertainty only when `drift`
also receives the declaration, captured bytes, deployment selection, and an
explicit evaluation date. See the
[dynamic-inventory contract](docs/dynamic-inventory.md).

## The manifest

Reachability needs three facts per tool that an ordinary tool schema does not
carry: the effect class, which argument spends value, and which scope the limit
is measured against.

```yaml
version: 1
agent: dispute-resolver
identity: spiffe://bank/agents/dispute-resolver

limits:
  total: { amount: 500, currency: GBP }
  depth: 8
  effects:                    # optional. an absent class is unbounded
    irreversible: 3           # at most three irreversible calls in one run

tools:
  - name: open_case
    effect: read              # read | write | irreversible
    produces: case            # mints a binding of scope "case"

  - name: issue_refund
    effect: irreversible
    principal: caller         # caller | service
    requires: [case]
    value_arg: amount
    scope_key: case           # the ceiling is per case
    ceiling: { amount: 500, currency: GBP }
    requires_approval: true
```

These annotations describe the bounded abstraction used by the search. They
do not model arbitrary preconditions, postconditions, or tool implementations.

A **cumulative constraint** makes a decision depend on qualifying earlier
actions. Its **limit** is the configured bound; its consumed state is what the
runtime has already counted. In manifest v1, a `ceiling` is the maximum
cumulative value one tool may spend against one binding of its `scope_key`.
`unbounded: true` marks a tool that can be called repeatedly to mint fresh
bindings, which is what turns a per-scope limit into no mandate-wide bound at
all.

## Commands

| Command | What it does |
|---|---|
| `mandate scan` | Derives a review-marked manifest skeleton from source or a local MCP/OpenAPI/A2A catalogue |
| `mandate drift` | Compares the declared mandate against the agent's source and fails when the two have separated |
| `mandate lint` | Single-manifest checks: separation of duties, ungated irreversible effects, service-account principals, invalid ceilings, and required scopes with no producer |
| `mandate reach` | Bounded search over a manifest or reviewed `--ir` snapshot for a legal call sequence that breaches a limit, reported as a counterexample |
| `mandate remediate` | Ranks rechecked tool-removal, approval and explicitly supplied ceiling candidates for a breached manifest, preserving named reachable tools and optionally supplied ordered workflows within the manifest model, with search limits disclosed; [repair guide](docs/remediation.md) |
| `mandate ir` | Exports a manifest as canonical Authority IR or structurally validates a snapshot without accepting its evidence as authority |
| `mandate inventory` | Imports local protocol catalogues as unreviewed declarations/IR, or validates declaration structure |
| `mandate conditions` | Structurally validates a tool-condition or condition-context artifact without accepting it as authority |
| `mandate delegations` | Structurally validates a delegation attachment or chain without accepting it as authority |
| `mandate producers` | Structurally validates a finite-producer boundary without accepting its sources as authority |
| `mandate continuity` | Structurally validates continuity evidence or reconciles whether consumed authority safely survives a named transition |
| `mandate cedar` | Exports mapped stateless policies with loss reporting, or validates, aligns and compares managed policy evidence. [Cedar export](docs/cedar-export.md) |
| `mandate rego` | Exports mapped stateless policies with explicit losses and native OPA tests. [Rego export](docs/rego-export.md) |
| `mandate deployment` | Checks gateway/policy configuration and joins captured decisions to tool attempts. [Drift](docs/deployment-drift.md), [reconciliation](docs/deployment-reconciliation.md) |
| `mandate fleet` | Queries declared agents, tools, owners and review expiry across local repository snapshots. [Fleet inventory](docs/fleet-inventory.md) |
| `mandate diff` | Effective-authority comparison of two manifests, including limits, preconditions, approvals, effects, and scope minting. `--record` emits a change record |
| `mandate review` | Checks named, evidenced and time-bounded acceptance of a pinned authority diff; findings remain unchanged and deployment approval is separate. [Review-record guide](docs/change-review.md) |
| `mandate verify` | Replays recorded tool calls against the manifest and fails closed when evidence required by a declared control is missing. Reads [OpenTelemetry traces](https://github.com/mrwersa/agentmandate/blob/main/docs/traces.md) with `--otel` |
| `mandate obligations` | Derives reviewable test obligations from reachable authority, and renders reviewed ones as an [AgentVerity](https://github.com/mrwersa/agentverity) decision suite |
| `mandate scenarios` | Exports reachable breach paths with blank environment, agent-input, and expected-control fields for human review and execution by an external evaluation harness |

Analysis commands support `--json` and return non-zero when findings or
unresolved required evidence need attention. `scan`, `inventory import`, and
`ir export` write artifacts to standard
output and are not gates. Exit codes and CI wiring: [docs/ci.md](docs/ci.md).

### When you need evidence attachments

Start with the ordinary manifest workflow above. Attachments are useful when
source code or manifest fields cannot establish a specific boundary:

| Need | Guide |
|---|---|
| Exchange a canonical reviewed authority snapshot | [Authority IR](docs/authority-ir.md) |
| Understand search depth, memory costs, and truncation | [Search bounds](docs/search-performance.md) |
| Resolve a dynamically supplied tool list | [Dynamic inventory](docs/dynamic-inventory.md) |
| Narrow a tool's effect using a reviewed input domain | [Conditional authority](docs/conditions-delegation.md) |
| Relate a tool to an ordered delegation chain | [Delegation](docs/delegation-v2.md) |
| Compare managed policy decisions with reviewed intent | [Managed Cedar](docs/cedar-import.md) |
| Establish a finite number of produced resources | [Producer boundaries](docs/bounded-producers.md) |
| Check whether consumed state survives a session or policy change | [Refund walkthrough](examples/continuity-refund/README.md) |
| Keep principal changes separate from session changes | [Principal observations](docs/principal-continuity.md) |
| Compare shared spend with a mandate budget under a reviewed binding | [Principal accounting](docs/principal-accounting.md) |
| Review policy-revision comparability and issuer treatment within an explicit scope | [Revision review](docs/revision-review.md) |
| Verify retained scalar state and next-request capacity at a handover | [Scalar handover](examples/scalar-handover/README.md) |

Each guide distinguishes structural validation from evidence eligible for
analysis. Parsing an artifact does not accept its claims. Continuity remains
experimental; principal observations currently leave mandate continuity
unresolved even when their evidence is eligible.

For example, the [GBP 1,000 refund mandate](examples/continuity-refund/manifest.json)
that has already spent GBP 600 should
retain that consumption after reconnecting. The synthetic walkthrough compares
a denied second GBP 600 refund with a reset that admits GBP 1,200 in total.

![A reviewed binding preserves consumed refund authority across a fresh session; the reset counterfactual overshoots the mandate](https://raw.githubusercontent.com/mrwersa/agentmandate/main/docs/assets/continuity-refund.svg)

## From authority to evaluation

AgentMandate produces two different test inputs:

- `obligations` names consequential decision points that reviewed bounded
  decision tests should reach
- `scenarios` preserves compound counterexample paths that a multi-step
  scenario test should attempt

It does not execute either test. Promptfoo, LangSmith, AgentCore Evaluations,
pytest, or an internal harness owns behaviour and outcome grading. AgentVerity
can qualify the repeated bounded decisions after correctness passes.

```text
reachability -> reviewed obligations and scenarios -> external evaluation
      ^                                               |
      |                                               v
manifest <- reviewed production incidents <- runtime policy and traces
```

[Read the complete evaluation-loop workflow](docs/evaluation-loop.md).

## Scope

Read every finding as **permitted by the reviewed mandate within this bounded
abstraction**. It is not proof that the model will choose the path or that an
undeclared downstream invariant will accept it.

What this does not do, on purpose:

- **No enforcement.** No proxy, no runtime interception, no blocking.
- **No data-flow reachability.** Finding that a read tool feeds an exfiltration path needs taint labels the manifest does not carry. Cumulative value and scope minting are what the current model supports honestly.
- **No model behaviour.** Whether the agent *would* take a path is a different question from whether it *may*. This measures permitted authority.
- **No session or budget broker.** A runtime session is not automatically the
  reviewed mandate, and a configured cumulative limit is not enough unless its
  consumed state remains attached to that mandate. Continuity across sessions,
  handoffs, and policy revisions is evidence-backed roadmap work, not a claim
  made by the current reachability command.
- **No inference of the fields that matter.** `mandate scan` reads agent source or an MCP catalogue and writes the skeleton, but it cannot know whether an effect is reversible or what a ceiling is measured against. It guesses conservatively and marks every guess `REVIEW`. Extract then annotate, never extract and trust.

Search is bounded by `limits.depth`. No breach at depth 8 is not proof that none exists at depth 20, and the report says when it truncated.

## Documentation

- [docs/README.md](docs/README.md) — a map of current contracts, experimental
  work, decision records, and evidence
- [DESIGN.md](DESIGN.md) — the authority model, why the search is shaped this way, and what was left out
- [docs/evaluation-loop.md](docs/evaluation-loop.md) — how authority analysis, scenario evaluation, runtime policy, and production feedback remain distinct
- [docs/test-obligations.md](docs/test-obligations.md) — decision-point obligations and the AgentVerity bridge
- [CONTRIBUTING.md](CONTRIBUTING.md) — branch and review workflow
- [SECURITY.md](SECURITY.md) — reporting, and what a manifest may contain
- [STABILITY.md](STABILITY.md) — what is guaranteed before 1.0
- [docs/ci.md](docs/ci.md) — the action, SARIF, the diff gate, and exit codes
- [ROADMAP.md](ROADMAP.md) — adoption work, planned model extensions, and the path to 1.0
- [CHANGELOG.md](CHANGELOG.md)

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
python -m pytest -q --cov=agentmandate --cov-fail-under=100
ruff check .
```

`main` is protected. Every change lands through a pull request with CI green.

## Status

Alpha. The version is in the badge above and on PyPI, so it is not repeated
here where it would go stale. The authority model is the part most likely to change,
because it has not yet been pointed at enough real tool graphs to know where it
is too coarse. Issues describing a graph it models badly are the most useful
thing you can file.
