HATS — Human-governed Agent Task Specification — is an open format for declaring exactly what role an AI agent is playing, what it’s allowed to do, who approves the rest, and how every decision is audited.
HATS unifies the three things that determine what an AI agent is allowed to do into a single, signable, versioned manifest. The persona governs tone and voice. The hat governs scope and capability. The policy engine, not the model, decides what runs.
It works with the agent runtime you already have — OpenAI, Anthropic, Bedrock, in-house models, MCP, A2A. The reference implementation is published under Apache 2.0 with zero runtime dependencies. The format is free to use, fork, and extend. The trademark on the name HATS is held by Pcnaid Inc. and licensed permissively for ecosystem use.
Don’t survive model behavior under load. A persistent enough user instruction will eventually override most system prompts.
Don’t survive a model swap. Don’t produce a unified audit trail. Don’t map to compliance frameworks.
Takes six to twelve months. Misses the compliance framework mappings. Often ends up shipped without an auditor in the room.
A YAML or JSON manifest declares the role’s mission, in-scope and out-of-scope behavior, requested capabilities, approval rules, and audit obligations. Validated against the HATS JSON Schema.
The manifest is signed (Ed25519) and pinned to a specific version. Any change is a new version, reviewable as a diff, signed again before it can ever be served to a runtime.
At session start, the runtime requests a runtime execution envelope for a (user, tenant, hat, persona) tuple. The policy engine returns the full set of effective permissions.
Every tool call passes through the policy engine before it executes. Allow, deny, or require approval. The decision is signed and hash-chained into the audit log.
Audit events are mappable to SOC 2, ISO/IEC 42001, EU AI Act Article 14, and NIST AI RMF controls. The report is the evidence, not a screenshot of the dashboard.
| Concept | What it governs | Example |
|---|---|---|
| Persona | Voice, tone, style, presentation. The how-it-feels layer. | Warm, concise, English. |
| Hat | Role contract. Mission, scope, capabilities requested, approvals required. | Client intake coordinator v0.1.0. |
| Capability | A specific tool, dataset, or action the hat is requesting authorization for. | records.read on customer_invoices. |
| Effective permissions | What the policy engine actually allows after evaluating all rules. | The decision that runs. |
Every hat is a versioned YAML or JSON file. Reviewable as a diff. Signed before deployment.
apiVersion: hats.dev/v0.1 kind: Hat metadata: id: client-intake-coordinator version: 0.1.0 owner: support@pcnaid.com spec: mission: | Help new clients complete intake forms and surface unpaid invoices. Never create, modify, or delete financial records. in_scope: - read customer profiles - summarize unpaid invoices for a tenant - collect contact information for new prospects out_of_scope: - records.write - records.delete - cross-tenant queries - refund authorization capability_requests: - id: records.read scope: tenant tables: [customers, invoices] - id: slack.notify scope: channel:#intake approvals: required_for: - any action with risk_level >= medium approver_role: customer_admin timeout_hours: 24 audit: hash_chain: true sinks: [customer_s3, otel] retention_days: 365
MCP tools are HATS capability_requests. The mapping is built into the spec.
Delegation packets between agents follow a HATS-compatible authority envelope.
Audit events emit as OTel log records with GenAI semantic conventions.
Repository-level conventions for declaring agent expectations alongside code.
Skim the JSON Schema, the example manifests, and the four ADRs that explain the design.
Open the specA zero-dependency Node 20 service that evaluates policies against the HATS schema locally.
The managed control plane built on HATS: signed manifests, hash-chained audit, SSO, compliance reports.
Book a demo