PIC Standard: Provenance & Intent Contracts

Local-first action gating for AI agents. Verify intent, provenance, and evidence before any high-impact tool call executes.

Contributors wanted. External contributors have already landed conformance vectors, CLI JSON output and Windows CI, and we are looking for more contributors and co-maintainers. Start with the call for contributors and the pinned good-first issues: small documentation tasks, each with the exact commands to check your work. TypeScript has a public implementation at pic-standard-ts; Go and Rust implementations and TypeScript evidence mode are planning tracks open to expressions of interest.

v0.9.1 (2026-10-14): Integration surface and a security-hardening fix. Adds structured JSON output to pic-cli verify, an optional, additive MCP guard pre-execution hook (on_allow), and live-argument binding: the MCP guard and HTTP bridge now bind the sanitized live tool arguments to the verified action.args and fail closed with the new PIC_ARG_BINDING_MISMATCH error code, completing tool binding (tool name and arguments) at that boundary. The PIC/1.0 wire format, PIC-CJSON/1.0, and proposal and evidence JSON schemas are unchanged from v0.9.0; the HTTP bridge error-code enum expands additively, and the conformance corpus grows from 84 to 91 vectors. See CHANGELOG for the full v0.9.1 story.

Evaluating PIC for an agent workflow? Start with the agent integration guide: choose an implementation, check signed evidence locally, see a complete signed-approval example, and understand what the execution boundary must enforce.

PIC is a lightweight, local-first protocol that forces AI agents to prove every important action before it happens. Agents must declare intent, impact, provenance, and evidence; PIC verifies everything and fails closed if anything is wrong.

PIC is not agent identity or delegation infrastructure; PIC is the action-bound verification contract that decides whether a high-impact tool call is justified to execute now.

No more hallucinations turning into wire transfers. No more prompt injections triggering data exports.

Example — when PIC blocks: A Slack message asks an LLM agent to send a $500 payment. PIC requires the agent to prove: where did this instruction come from? Is the source trusted? Is there evidence the invoice is real? The Slack message carries no trusted provenance, the claim has no backing evidence — PIC returns block. The payment tool never executes.

Table of Contents

• Why PIC?
• Quickstart
• The PIC Contract
• How It Works
• Evidence Verification
• Keyring (Trusted Signers)
• Implementations
• Integrations
• RFC & Prior Art
• Roadmap
• Project info
• Contributing

Why PIC?

Guardrails constrain what the model says. PIC constrains what the agent is allowed to do based on verifiable provenance + evidence.

PIC is built for agent frameworks, internal tool gateways, and production systems where high-impact actions must be justified before execution.

• Stops prompt injections & blind tool calls at the action boundary
• Works 100% locally: zero cloud, zero data leaves your machine
• Plugs into your stack in minutes: LangGraph, MCP, OpenClaw, Cordum
• Open-source (Apache 2.0): audit it, fork it, own it

Quickstart

Try the verifier locally against a sample high-impact proposal in under a minute.

pip install pic-standard

# Verify an example proposal
pic-cli verify examples/financial_irreversible.json

# Evidence-aware verification (hash + signature; hash proves integrity,
# signature provides authority for trust upgrade under v0.8.3)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_hash_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_hash_ok.json --verify-evidence

# Evidence-aware verification (signature — requires example keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence

Why the keyring on the hash example? Under v0.8.3 evidence semantics, a matching hash proves content-integrity of the referenced file bytes but does not, by itself, upgrade provenance trust. The signature evidence, verified against PIC_KEYS_PATH, supplies the authority-bearing trust upgrade for the money-impact action. See docs/spec-evidence.md §8 and issue #133.

Optional extras:

pip install "pic-standard[langgraph]"  # LangGraph PICToolNode
pip install "pic-standard[mcp]"        # MCP tool guarding
pip install "pic-standard[crypto]"     # Ed25519 signature evidence

From source (contributors):

git clone https://github.com/pic-standard/pic-standard.git
cd pic-standard && pip install -e ".[langgraph,mcp,crypto]"
pytest -q

The PIC Contract

PIC is enforced at the moment before tool execution. The agent must emit a structured Action Proposal that can be validated, verified, and bound to the intended tool.

Rule: For high-impact proposals, at least one claim must reference evidence from trusted provenance. Fail-closed.

How It Works

graph TD
    A[User input / external context] --> B[AI Agent / Planner]
    C[Internal data / system context] --> B
    B --> D[PIC Action Proposal JSON]
    D --> E[PIC Verifier]
    E --> F{Intent, provenance, impact, evidence valid?}
    F -- Yes --> G[Tool Executor]
    F -- No --> H[Blocked / Audit Log]
    G --> I[API / DB / File / Payment / External Action]

How PIC Differs from Receipt / Audit / Reputation Systems

PIC is a pre-execution action-verification contract - a parallel surface in the agent-safety stack, not a primitive in a shared substrate. PIC decides at the action boundary whether a high-impact tool call is justified to execute now. Post-execution systems - bilateral receipts, signed audit logs, trust/reputation scores - record what already happened and are architecturally distinct.

PIC's pre-execution surface can contribute to Article 12-style traceability on the decision side: a verified Action Proposal is a structured decision artifact that may be incorporated into a high-risk AI system's record-keeping and logging architecture. PIC alone is not Article 12 compliance; it complements the broader system-level logging and retention duties in Articles 12 and 19. A post-execution attestation surface bound to the same primitives is drafted in docs/attestation-object-draft.md, kept local-first and operator-controlled by design.

Rule of thumb: if a system asks "should this action be allowed to run?", that's PIC's surface. If it asks "did this action run, and what's the agent's reputation?", that's a complementary post-execution surface — not a layer PIC sits inside.

Evidence Verification

PIC supports deterministic evidence verification. Authority-bearing signature evidence, verified against the configured keyring, can upgrade matching provenance[].trust in-memory. Hash evidence establishes content integrity for referenced bytes only and does not, by itself, upgrade trust. See docs/spec-evidence.md section 8.

Ed25519 signature verification requires pip install "pic-standard[crypto]".

# Verify hash evidence
pic-cli verify examples/financial_hash_ok.json --verify-evidence

# Verify signature evidence (requires keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence

Full guide: docs/evidence.md

Canonicalization (v0.8.0+): PIC Canonical JSON v1 (PIC-CJSON/1.0) defines the byte-exact serialization rules used when PIC hashes or signs JSON values. The normative spec is docs/canonicalization.md; a pure-stdlib reference implementation lives at pic_standard.canonical (canonicalize(), sha256_hex(), intent_digest_hex()). In v0.8.0 this is an additive capability — existing signature verification paths continue to work as in v0.7.x; wiring canonicalization into attestation-object-backed signatures is scheduled for a later release. Conformance vectors live under conformance/canonicalization/ and execute on every PR via the PIC Conformance CI job.

Keyring (Trusted Signers)

Signature evidence requires a keyring of trusted public keys with expiry and revocation support.

pic-cli keys                        # Inspect current keyring
pic-cli keys --write-example        # Generate starter keyring

Custom resolvers (v0.7+): As of v0.7, trust resolution is injectable and local-first. PIC no longer reloads the default keyring per signature, and custom resolvers can plug into the verifier and pipeline directly. Implement the KeyResolver protocol to use your own trust backend or preloaded trust source (HSM-backed service, Vault-managed keys, cached remote keyring, etc.):

from pic_standard import KeyResolver, StaticKeyRingResolver

Trust controls (v0.9.0a2+): strict_trust=True is the secure default: all inbound provenance trust is sanitized to untrusted, and only authority-bearing evidence verification, currently signature evidence, can upgrade matching provenance trust. Legacy compatibility mode (strict_trust=False) remains callable and emits PICLegacyTrustModeWarning at construction. See docs/migration-trust-sanitization.md for migration guide.

Full guide: docs/keyring.md

Implementations

• Python reference implementation: this repository, published as pic-standard on PyPI.
• TypeScript implementation: pic-standard/pic-standard-ts, passing the shared conformance corpus for canonicalization, core, and trust_sanitization modes. Advisory differential CI in this repository compares Python and TypeScript envelopes on every PR targeting main.
• Next high-value tracks: Go and Rust implementations. See the call for contributors if you want to own one.

graph TD
    A[Shared conformance corpus] --> B[Python reference verifier]
    A --> C[TypeScript verifier]
    B --> D[Python envelope]
    C --> E[TypeScript envelope]
    D --> F[Differential CI]
    E --> F
    F --> G{Same semantic result?}
    G -- Yes --> H[Cross-implementation parity signal]
    G -- No --> I[Diff artifact: py.json / ts.json / diff.txt]

Integrations

LangGraph

Guard any tool node with PICToolNode:

pip install "pic-standard[langgraph]"

PICToolNode now accepts verify_evidence, strict_trust, policy, and key_resolver for full pipeline configuration (v0.7.5+).

MCP (Model Context Protocol)

Enterprise tool guarding with fail-closed defaults, request correlation, DoS limits, and evidence sandboxing:

pip install "pic-standard[mcp]"

Full guide: docs/mcp-integration.md

OpenClaw

TypeScript plugin for OpenClaw AI agents (pic-gate, pic-init, pic-audit hooks):

pic-cli serve --port 7580
cd integrations/openclaw && npm install && npm run build

Full guide: docs/openclaw-integration.md

Cordum

Go Pack providing PIC verification as a Cordum workflow gate step with fail-closed three-way routing.

Full guide: docs/cordum-integration.md

HTTP Bridge (any language)

For non-Python integrations, PIC exposes an HTTP bridge:

pic-cli serve --port 3100
# POST /verify   — verify an action proposal
# GET  /health   — liveness check
# GET  /v1/version — package + protocol version

RFC & Prior Art

RFC-0001: PIC/1.0 — Provenance & Intent Contracts for AI Agent Action Safety

Formal specification covering scope, threat model, security properties, conformance levels, and prior art differentiation. Published as a defensive publication with a SHA-256 fingerprint manifest: docs/RFC-0001.SHA256.

Verify locally: sha256sum -c docs/RFC-0001.SHA256

Canonical Vocabulary — authoritative glossary of PIC terminology cited by external crosswalks and registries.

Roadmap

• Core verifier, CLI, schema, policy system
• Evidence verification (SHA-256 hash + Ed25519 signatures)
• Anchor integrations (LangGraph, MCP, OpenClaw, Cordum)
• Injectable key resolution + hot path fix (v0.7)
• Trust hardening + attestation object draft (v0.7.5)
• Canonicalization spec (PIC Canonical JSON v1) + reference implementation (v0.8.0)
• Initial conformance suite (canonicalization + core modes) with CI runner (v0.8.0)
• TypeScript local verifier for canonicalization, core, and trust_sanitization
• Cross-implementation differential CI (Python vs TypeScript semantic envelopes)
• Evidence-mode TypeScript parity
• Go/Rust verifier parity
• Normative semantics (MUST/SHOULD spec document)
• OpenAPI spec + guard hardening (structured audit logs, request correlation)

Project info

• Security policy — see SECURITY.md. Report vulnerabilities privately via GitHub Security Advisories; do not file public issues for security reports.
• Code of conduct — see CODE_OF_CONDUCT.md. PIC follows the Contributor Covenant 2.1. Reports go to team@madeinpluto.com.
• Citation — see CITATION.cff for full citation metadata. The Zenodo concept DOI 10.5281/zenodo.18725562 (badged at the top of this page) resolves to the latest archived release on Zenodo; per-version DOIs are listed on the Zenodo record.
• Foundation-track feedback — PIC Standard has undergone AAIF project-proposal review. The technical positioning was recognized; the current focus is expanding multi-organization maintainership, production adoption, and standards-track readiness.
• Independent reviews — PIC-authored provenance notes for independent evaluations of PIC releases live under docs/independent-reviews/. These pages do not redistribute reviewer-authored sealed reports, PDFs, or methodology documents, and are not certifications, endorsements, audits, or general security guarantees.
• License — Apache-2.0; see LICENSE (also badged at the top of this page).

Contributing

We welcome contributions! See CONTRIBUTING.md for how to propose changes or report issues.

We're actively seeking:

• Security researchers to stress-test causal logic
• Framework authors to build native integrations
• Enterprise architects to define domain Impact Classes

Good first contribution areas right now: documentation walkthroughs of the examples and newcomer setup guides (see the good first issues). Larger tracks (Go and Rust verifiers, TypeScript evidence mode, security review of trust sanitization behavior) start with an expression of interest in the call for contributors.

If you find PIC useful, please consider giving us a star on GitHub: it helps attract more security experts and framework authors into the community.

Issues & ideas: GitHub Issues

Maintained by @fmsalvadori   MadeInPluto