PIC Standard: Provenance & Intent Contracts

Require verifiable evidence before your AI agent acts.

Local-first. Open source. Your policy and trusted keys.

Before an agent makes a payment, exports sensitive data, or deletes a resource, it must declare what it intends to do, which sources informed the decision, and what evidence supports its claims.

PIC adds a verification gate before tool execution. It checks the action proposal, verifies supporting evidence against your trusted keys, and enforces the required connection between claims and trusted provenance. Your integration blocks execution when verification fails.

The intent, provenance, claims, and proposed action travel together in a structured contract. Canonical signed attestations bind supporting evidence to the specific action being proposed.

Try PIC · See a signed approval in action · Integrations · Specifications · Contribute

flowchart TD
    agent["AI Agent proposes an action"]
    proposal["Action Proposal: intent, impact, provenance, claims, evidence, action"]
    pic{"PIC verification"}
    integration["Integration enforces the decision before tool execution"]
    blocked(("Execution blocked"))

    agent --> proposal --> pic
    pic -->|"Checks pass"| integration
    pic -->|"Checks fail"| blocked

PIC checks the proposal and supporting evidence. The execution integration must enforce the decision and ensure the tool receives the verified arguments.

Why PIC?

An agent may have permission to use a payment tool and still act on a forged invoice, an injected instruction, or an unsupported claim that someone approved the transaction.

PIC gives your application a contract for checking the proposed action and its supporting evidence before execution. You decide which tools require PIC and which signing keys to trust. Verification runs in code, without asking a model whether its own decision was justified.

• Require evidence for high-impact actions. Money, privacy, and irreversible actions require a claim linked to trusted provenance under PIC's core rule.
• Reject self-asserted trust. Incoming provenance labels are sanitized to untrusted by default. Accepted signature evidence can establish trust through your configured keyring.
• Bind evidence to the proposed action. Canonical attestations bind the tool, arguments, impact, claims, and provenance IDs. They also support intent binding and expiry checks.
• Check the arguments at the tool boundary. The Python MCP guard and HTTP bridge compare the submitted live arguments with the verified proposal and reject mismatches.
• Keep verification under your control. Run locally, use your own trusted keys, and integrate through Python or the HTTP API. No hosted PIC account or model API key is required for verification.

The PIC contract

Every Action Proposal brings the decision and the intended tool call into one verifiable structure.

PIC defines seven impact classes: read, write, external, compute, money, privacy, and irreversible.

For money, privacy, and irreversible, at least one claim must reference trusted provenance. With strict trust enabled, an agent cannot satisfy that requirement simply by writing "trust": "trusted".

Operator policy maps tools to impact classes and determines where proposals and evidence verification are required. Applications can impose additional requirements, such as a particular approver or a refund-specific argument schema.

See the contract in action

A merchant approves a €40 EUR refund on payment pay_A. The agent submits a proposal containing the refund intent, merchant provenance, approval references, signed evidence, and the exact refund action.

PIC verifies the signature and its binding to the proposal. The example's execution wrapper checks the refund workflow's requirements and calls the tool only after those checks pass.

The example includes 22 verification and dispatch cases, with tool-call counts and checks on the actual arguments received. Two deliberately broken wrappers verify that the suite detects premature execution and substituted arguments.

It uses a harmless recording tool; no money moves. The example documents which checks belong to PIC and which belong to the refund workflow.

Run the signed-refund example →

Quickstart

Install the Python verifier

Python 3.10 or later:

python -m pip install "pic-standard[crypto]"

The crypto extra enables Ed25519 signature verification. Install pic-standard without extras when you do not need signature verification.

Verify valid and tampered evidence

The sample files live in the repository. From a checkout, install the source and run the fixtures:

git clone https://github.com/pic-standard/pic-standard.git
cd pic-standard
python -m pip install -e ".[crypto]"

On macOS or Linux:

export PIC_KEYS_PATH="$PWD/pic_keys.example.json"
pic-cli verify examples/financial_sig_ok.json --verify-evidence --json
pic-cli verify examples/failing/financial_sig_bad.json --verify-evidence --json

On PowerShell:

$env:PIC_KEYS_PATH = "$PWD/pic_keys.example.json"
pic-cli verify examples/financial_sig_ok.json --verify-evidence --json
pic-cli verify examples/failing/financial_sig_bad.json --verify-evidence --json

The valid fixture returns "ok": true; the tampered fixture returns "ok": false with PIC_EVIDENCE_FAILED. These commands verify evidence without executing a tool. The bundled demo keys expire on 1 January 2027.

These small fixtures demonstrate legacy signature verification. For a complete approval bound to an action, follow the signed-refund example, which has its own pinned installation and execution instructions.

Next: integration guide · signature walkthrough · examples index

Integrations

Optional Python extras:

python -m pip install "pic-standard[mcp,crypto]"
python -m pip install "pic-standard[langgraph,crypto]"

Configure the tools that require PIC, enable evidence verification, and supply trusted keys. The integration guide covers the complete execution-boundary setup.

Argument binding in v0.9.1: the MCP guard and HTTP bridge check live arguments against the verified proposal. The LangGraph node does not yet perform that comparison; applications using it must enforce it before dispatch.

The HTTP bridge verifies a submitted call; its caller controls execution. A successful HTTP response is not necessarily an allow decision: inspect allowed.

Evidence and trusted keys

PIC supports two evidence types:

Canonical PIC-ATT/1.0 attestations bind the tool, impact, ordered provenance IDs, arguments digest, and claims digest. An intent digest and expiry are checked when present. A workflow can require those fields, as the refund example does.

Trusted keys are configured outside agent-controlled proposals. PIC supports key expiry, revoked-key lists, and a KeyResolver interface for operator-managed trust sources.

pic-cli keys
pic-cli keys --write-example

File evidence is restricted to a configured evidence directory and bounded by size limits. Proposal and evidence limits, canonicalization checks, and structured error codes support predictable rejection of malformed input.

Evidence guide · Keyring guide · Error reference

Security model

PIC operates between an agent's proposal and tool execution. Identity systems, task-scoped permissions, and execution logs can work alongside PIC.

Its verification checks structured declarations and evidence. It does not infer the model's private reasoning, prove that every influencing source was disclosed, or decide whether a signer made a sound business decision.

Your application owns the trusted keys, tool policy, and execution path. It must prevent bypass, enforce any workflow-specific approval requirements, and execute the checked arguments. Approval consumption, replay prevention, provider idempotency, and execution reconciliation belong to the surrounding workflow.

An allow decision records successful verification; it does not establish that the tool executed or that the intended effect occurred.

For new signed-approval workflows, use canonical attestations with the required binding and validity fields. Legacy payload signatures remain supported in v0.9.1 for compatibility and do not provide the same action binding.

Report vulnerabilities privately through GitHub Security Advisories. See SECURITY.md.

Specifications and conformance

PIC is an open protocol with a Python reference implementation and a separate TypeScript implementation.

The shared corpus contains 91 conformance vectors in v0.9.1:

The Python verifier covers all four modes. TypeScript implements canonicalization, core, and trust sanitization; evidence-mode parity remains a completion item. Advisory differential CI compares the implementations' results for their shared modes.

From an installed repository checkout:

python -m conformance.run
python -m conformance.run --json

Specification entry points:

• Specification status: implemented versions, draft status, and conformance profiles.
• Core verifier semantics: proposals, trust, impacts, and verifier outcomes.
• Evidence semantics: hashes, signatures, trust upgrades, and canonical attestation verification.
• Canonical JSON: the byte-level serialization contract.
• Attestation object: the signed action representation.
• RFC-0001: the original defensive publication and protocol baseline.
• Vocabulary: shared terminology.

Core, Evidence, and Attestation specifications remain drafts ahead of the v1.0 freeze. PIC/1.0 is the protocol identifier; the current Python package is v0.9.1.

Releases and roadmap

v0.9.1 adds MCP/HTTP live-argument binding, an optional MCP pre-execution hook, and structured CLI verification output. See the changelog.

The v1.0 work focuses on:

• Completing Python/TypeScript conformance across all modes, including evidence.
• Finalizing Core, Evidence, and Attestation specifications.
• Making strict trust and canonical signing the conformant modes, with legacy behavior clearly separated.
• Resolving remaining semantic ambiguities before freezing the contract.

See the full roadmap and release process.

Contributing

External contributors have already landed conformance vectors, CLI JSON output, Windows CI, and documentation. Contributions from security researchers, framework authors, and protocol implementers are welcome.

• New to PIC? Start with the good-first issues and contribution guide.
• Building an implementation or integration? Join the call for contributors. TypeScript evidence mode and Go/Rust implementations are useful tracks.
• Testing the security model? Try the signed-refund cases, add a conformance vector, or report a vulnerability privately.

Please include the version, configuration, expected outcome, and a minimal reproduction with technical reports.

Project information

• License: Apache-2.0. The external Cordum Pack has its own license.
• Governance: GOVERNANCE.md · Maintainers · Code of conduct.
• Independent review: Provenance notes describe PIC-maintained regressions arising from independent evaluation of earlier releases.
• Foundation-track discussion: AAIF project-proposal review.
• Citation: CITATION.cff · Zenodo DOI.

Created and maintained by Fabio Marcello Salvadori, with the PIC Standard community.

If PIC is useful to your work, a GitHub star helps others find it. Questions and ideas are welcome in Issues and Discussions.