AgentHook™ is an open technical specification for AI-agent runtime evidence: verified runtime contracts, lifecycle signals, material tool activity, human approvals, policy denials, model interactions, publisher manifests, and runtime control attestations.
Without runtime evidence, AI governance is just policy. AgentHook makes it provable while staying intentionally vendor-neutral.
Policies, risk registers, and management systems are necessary, but they cannot prove what an agent actually did at runtime. Agent runtimes expose prompts, model calls, tool calls, approvals, denials, and responses inconsistently. Without a shared envelope, every operator rebuilds the same evidence plumbing per vendor, and auditors cannot compare agent behaviour across systems.
ISO 42001, NIST AI RMF, EU AI Act logging obligations, state AI laws, OpenTelemetry, CloudEvents, W3C Trace Context, IETF RATS, SPIFFE/SPIRE, in-toto/SLSA, Sigstore, C2PA, and policy engines such as Microsoft AGT solve adjacent problems. AgentHook defines the missing agent-specific event grammar that can feed those systems.
ISO/IEC 42001, NIST AI RMF, EU AI Act obligations, and US state AI laws (Colorado AI Act, with California, Texas, and others in motion) define process, accountability, and risk vocabulary. AgentHook supplies the runtime evidence those programmes can use.
OpenTelemetry, CloudEvents, and W3C Trace Context move telemetry through systems. AgentHook defines the AI-agent lifecycle semantics carried in that telemetry.
IETF RATS, SPIFFE/SPIRE, in-toto/SLSA, Sigstore, and C2PA inform identity, provenance, and attestation design. AgentHook applies those patterns to agent runtime controls.
AgentHook publisher manifests declare the runtime, source label, supported lifecycle events, limitations, installer metadata, and verification status in a single local-first file.
Policy engines, semantic gates, workflow systems, redaction systems, and custom subscribers can consume AgentHook events to allow, deny, ask, redact, enrich, or audit agent behaviour.
SOC 2 Type II, ISO/IEC 27001, and emerging AICPA SOC for AI work define the evidence formats assurance professionals expect. AgentHook produces runtime events those programmes can ingest as primary evidence.
Reference implementations can prove the specification in practice. Conforming implementations do not need any specific bus, policy engine, subscriber, or vendor runtime.
AgentHook does not certify legal or regulatory compliance. It does not replace a GRC platform, an AI management system, or an audit programme. It makes runtime evidence portable so those systems can do their work.
A draft non-breaking extension that lets a publisher declare which hooks, gates, subscribers, consolidation rules, and fail modes are active for the current session. Attestation distinguishes verified runtime facts from user-authored prompt text and is carried inside the existing envelope.
Read AHP-004 →A draft AgentHook Proposal defines optional metadata.governance_context fields for carrying current task, policy, and workflow context inside the existing envelope. The metadata is advisory context for policy, audit, workflow, and observability subscribers; it is not an authorisation decision by itself.
A draft enterprise metadata convention that lets participating publishers describe their runtime instance, device or workload binding, approval reference, and verification strength. AgentHook does not claim network-wide AI discovery; activity outside the registry remains the responsibility of existing MDM, EDR, SASE, identity, and procurement controls.
Read AHP-006 →Regulators, boards, auditors, accreditors, insurers, and investors need to see patterns across agents, models, and institutions, not just review policies in isolation. AgentHook does not replace your risk framework, audit programme, or management system. It makes them verifiable by giving every entity the same runtime evidence grammar.
Compare evidence when multiple entities use the same agent runtime, model provider, or tool integration.
Record where a human approved, denied, or escalated agent activity before execution.
Detect changes in active subscribers, model metadata, publisher versions, and runtime control posture.
Keep allow, deny, ask, override, and workflow decisions comparable across teams and entities.
Today, policy, audit, memory, workflow, and observability tools have to be rebuilt per agent provider because each runtime exposes a different hook surface. With AgentHook, every conforming runtime emits the same envelope, and a single subscriber connects to all of them.
Each compliance tool has to know each runtime's hook surface, fail-mode behaviour, and metadata shape. Every new vendor adds another integration. Every change to a vendor's hooks breaks the audit trail.
Runtimes emit a standard envelope. Compliance tools subscribe once and work across every conforming runtime. Vendor changes are absorbed by the envelope contract, not by every downstream subscriber.
AgentHook Runtime Attestation is a publisher-supplied declaration of the contract, hooks, gates, subscribers, fail modes, and consolidation rules active in the current session. It records runtime facts. User-authored prompt text is never treated as equivalent to a verified runtime contract.
User-authored text can claim that a gate exists, that a PIN works, or that a policy is active. Runtime attestation separates those claims from verified runtime facts supplied by the publisher or adapter.
AGENTHOOK.md and agenthook.lock.json before agent execution.RuntimeContractLoaded, then routes lifecycle and tool-activity events to subscribers.{
"type": "agenthook.runtime_attestation",
"schema_version": "1.0",
"session_id": "sess-abc123",
"nonce": "session-bound",
"runtime_contract": {
"id": "example-prod",
"path": "./agenthook.lock.json",
"hash": "sha256:...",
"signature_valid": true
},
"active_subscribers": [
{
"name": "policy-gate",
"role": "policy_gate",
"mode": "enforce",
"events": ["PreToolUse"]
}
],
"consolidation": {
"strategy": "deny_wins"
},
"claims": {
"user_text_is_not_attestation": true,
"prompt_injection_is_not_a_contract": true,
"does_not_override_model_safety": true
}
}
A serious agent standard cannot rely on pasting governance instructions into a prompt. AgentHook defines a runtime contract that conforming agents and publishers discover, verify, load, and attest before the agent acts.
The human-readable file explains the operating contract. The lock file is the canonical machine-readable contract. The signature turns the contract into verifiable evidence.
AGENTHOOK.md describes hooks, audit expectations, tool-activity rules, human approval rules, and operational boundaries.agenthook.lock.json records required hooks, hashes, policy references, transport expectations, and conformance mode.agenthook.signature signs the contract set for high-assurance operation.RuntimeContractLoaded records the active contract id, version, hash, signature state, and required hooks.{
"event_type": "RuntimeContractLoaded",
"contract": {
"id": "example-prod",
"version": "2026.05.10",
"path": "./agenthook.lock.json",
"human_readable_path": "./AGENTHOOK.md",
"hash": "sha256:...",
"signature_valid": true,
"required_hooks": [
"SessionStart",
"UserPromptSubmit",
"PreToolUse",
"ToolActivity",
"HumanDecision",
"EvidenceSeal"
],
"conformance_mode": "gold"
}
}
Bronze publishers may discover AGENTHOOK.md and record its digest. Silver publishers should load agenthook.lock.json. Gold publishers should verify a signature. High-assurance publishers must not enter high-assurance mode if the required runtime contract is missing, modified, or unsigned.
A conforming publisher SHOULD ship an agenthook.publisher.json file at the repository root. The manifest gives collectors and operators one place to inspect identity, event coverage, limitations, configuration files, and verification status before live events are observed.
The manifest does not install code and it does not make policy decisions. It is declarative metadata that lets a collector show what a publisher claims to support, then verify that claim by observing real runtime events.
uk.agenticthinking.publisher.anthropic.claude-code.{
"schema": "https://agenthook.org/schemas/publisher-manifest.v1.json",
"schema_version": "1.0",
"publisher_id": "uk.example.publisher.runtime",
"display_name": "Example AgentHook Publisher",
"maintainer": {
"name": "Example Maintainer",
"url": "https://example.com"
},
"runtime": {
"vendor": "Example",
"name": "Example Agent CLI",
"versions_tested": ["1.0.0"]
},
"agenthook": {
"version": "0.1",
"source": "example-cli",
"events": {
"SessionStart": "supported",
"UserPromptSubmit": "supported",
"PreLLMCall": "not_exposed",
"PostLLMCall": "not_exposed",
"PreToolUse": "supported",
"PostToolUse": "supported",
"ModelResponse": "partial",
"SessionEnd": "not_exposed",
"AgentHandoff": "not_exposed",
"ErrorOccurred": "not_exposed"
}
},
"entrypoints": {
"command": "bin/example-gate",
"installer": "install.sh"
},
"config": { "files": ["~/.example/hooks.json"] },
"limitations": ["Raw LLM hooks are not exposed."],
"verification": {
"self_attested": true,
"conformance": "pending",
"last_tested": "2026-04-28",
"commands": ["example-gate --self-test"]
}
}
Any host language, any transport. The wire format below is the core contract a publisher commits to. A subscriber listens and responds with verdicts the publisher honours. Runtime contracts are loaded before execution, then attested in the event stream. Publisher manifests sit beside the code, declaring identity and hook coverage. Validate every event against envelope.schema.json.
import httpx, uuid, datetime as dt
def emit(event_type, **fields):
event = {
"schema_version": 1,
"event_id": str(uuid.uuid4()),
"event_type": event_type,
"timestamp": dt.datetime.now(dt.timezone.utc).isoformat(),
"source": "your-runtime",
**fields,
}
httpx.post("http://agenthook-collector:18800/event", json=event, timeout=5)
emit("PreToolUse", tool_name="Bash", tool_input={"command": "git push"})from fastapi import FastAPI
app = FastAPI()
@app.post("/event")
async def receive(event: dict):
if event["event_type"] == "PreToolUse":
cmd = event.get("tool_input", {}).get("command", "")
if "git push" in cmd:
return {"verdict": "deny", "reason": "review push first"}
return {"verdict": "allow"}The example uses a neutral collector URL. Any conforming publisher, bus, adapter, or collector may implement the envelope and delivery semantics. Reference implementations exist; they are not required for conformance. Publishers should also ship agenthook.publisher.json so collectors can inspect declared coverage before verifying live events.
AgentHook defines the wire-format envelope every event must carry, the canonical event vocabulary every conforming runtime can emit, the standard metadata keys per event type, and the hook delivery semantics (sync versus async, fail-mode behaviour). It is implementation-neutral: any transport, any host language, provided the envelope and semantics are honoured.
Implementations may emit additional event types using PascalCase names. Subscribers may ignore unknown types. Buses must not reject events on unrecognised event_type.
A publisher claims a tier. A test rig verifies the claim. The self-test harness is open source and free for any implementer. A hosted Conformance-as-a-Service is operated by the steward for procurement-grade signed reports, on a cost-recovery basis. Conformance certification is never used to gate participation in the working group or in the specification.
Publisher emits the core lifecycle event types with the envelope format. Required fields populated, valid JSON, valid event_id, valid timestamp. Runtime contract digest recorded where available.
Tests envelope schema validation, required field presence, event type emission, and timestamp validity across the canonical lifecycle.
Bronze plus agenthook.lock.json loading, matched Pre and Post LLM call pairs, model/provider metadata, token counts, and response content.
Tests Bronze conformance plus runtime contract loading and matched PreLLMCall/PostLLMCall pairs with correct model, provider, and token-count metadata.
Silver plus signature verification, reasoning capture when exposed, correlation IDs, material ToolActivity, human decisions, incident signals, and evidence sealing.
Tests Silver conformance plus signature validation, reasoning capture where exposed, correlation IDs linking sub-agent calls and retries, and high-assurance audit events.
A minimal reference fixture emits the canonical lifecycle, runtime contract, tool-activity, human-decision, incident, and evidence-sealing events through a collector or bus with a single preflight command. It is deliberately small: a fixture for hook coverage, ordering, metadata, and reasoning visibility, not a production agent SDK.
agenthook-fixture --preflight emits a deterministic lifecycle run. Provider reasoning smoke tests are configured through a compatible model endpoint; the standard itself remains LLM-agnostic.
AgentHook Conformance Fixture on GitHub →
A current audit of which AgentHook lifecycle events each major agent runtime exposes, scored against the conformance tiers. Any runtime can move tier by exposing the missing hooks; the AgentHook specification itself does not need to change for them to do so.
Audit method: direct inspection of each runtime's published hook surface and public Agentic Thinking publisher repositories as of 7 May 2026, scored against the AgentHook v0.1 draft specification. Tiers shown are preliminary indicators based on hook-surface inspection and publisher self-attestation only; formal Bronze, Silver, and Gold tiers will be awarded by the AgentHook conformance test harness once it ships alongside specification v1.0. Runtime providers may self-attest by Pull Request to the AgentHook repository. Self-attested rows will be marked accordingly. This audit is for technical interoperability comparison, not procurement guidance. Next scheduled review: 21 May 2026, then fortnightly while publisher coverage is changing.
Pending rows will be filled as each runtime's hook surface is reviewed and validated against the conformance test suite. Self-attested rows and test harness verified rows will be marked accordingly. Microsoft Agent Governance Toolkit is tracked as a control/subscriber layer, not as an agent runtime publisher.
The specification is published and stewarded by Agentic Thinking Limited (UK), a private company limited by shares (company number 17152930). Stewardship is provisional. The steward will transfer governance to a neutral, vendor-independent foundation when the specification has reached version 1.0 stability and at least one of the following has occurred: three or more leading commercial agent runtime providers have implemented AgentHook natively; three or more independent open-source runtimes have implemented it natively, with at least one alternative AgentHook-conformant collector existing in the wild; or the European AI Office, NIST, the UK AI Safety Institute, or an equivalent recognised body has cited the specification in formal published guidance. The following commitments are binding on the steward and any successor.
The licence shall not be replaced, restricted, or supplemented with additional terms by the steward or any successor.
No fee may be charged for the right to implement the specification, claim conformance, or use the AgentHook name in describing an implementation.
Any individual or organisation may submit Proposals and contribute to working-group discussion. Vote-eligible seats are limited to founding and elected members; this does not restrict contribution.
Royalty-free, irrevocable patent licence to any party implementing the specification. Survives any change of stewardship.
The specification may be forked at any time under Apache 2.0. The steward may not assert trademark rights against forks (provided the forks do not represent themselves as the official specification).
Any amendment to the Charter or to these commitments requires twelve months' public notice and unanimous Working Group approval.
These commitments are documented in CHARTER.md and are binding on the steward and any successor. The Working Group composition, voting rules, and AgentHook Proposal (AHP) process are documented in GOVERNANCE.md. Stewardship transfer is conditional on the triggers above and is not gated on a calendar.
The AgentHook specification is accompanied by a draft technical paper that sets out the problem, the architecture, the envelope model, runtime attestation, governance context metadata, and conformance tiers in detail.
Ruocco, P. (2026). AgentHook: A Runtime Evidence Standard for Auditable AI Agent Governance. Zenodo.
DOI: 10.5281/zenodo.19853376.
Working group composition is being finalised ahead of the public draft. Any individual or organisation may contribute to discussion in GitHub Issues. Substantive specification changes follow the AgentHook Proposal (AHP) process.
Envelope format, ten canonical event types, hook delivery semantics, conformance tiers.
Substantive changes go through the AHP process, modelled on Python PEPs and Rust RFCs.
Declare publisher identity, runtime, supported events, limitations, and verification commands in one local-first file.
Questions, edge cases, integration notes, conformance test feedback. All on GitHub.
The provisional steward of the AgentHook specification and maintainer of reference implementation work.