AgentHook™ is an Apache 2.0 technical specification for AI-agent runtime evidence. It defines a structured envelope for lifecycle events: prompts, tool calls, model interactions, human approvals, policy denials, reasoning exposure, publisher manifests, and runtime control attestations.
Without runtime evidence, AI governance is policy without proof. AgentHook makes agent behaviour comparable, auditable, and 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.
Tool calling remains provider-specific. AgentHook standardizes the governance evidence around actions: canonical identity, provider translation, risk, validation, redaction, approval, retry, execution, and requested-versus-executed comparison.
An ask verdict is a governance state, not a transient tool failure. Publishers must stop equivalent retries while approval is pending, surface the workflow reference, and may poll until a human decision allows or denies continuation.
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 →A draft convention for recording ask, approval, denial, retry, and resume state as runtime evidence, so paused autonomous-agent work can be reconstructed without treating approval as a transient tool error.
Read AHP-007 →A draft trust convention for reporting whether active hook entries are reviewed, modified, untrusted, disabled, unknown, or unsupported across runtimes, publishers, buses, and enterprise registries.
Read AHP-008 →A draft convention for AgentHook.md, AGENTHOOK.md, agenthook.lock.json, and runtime contract loading events, giving agents a stable local contract without making prompt text authoritative.
A draft convention for goal identifiers, session lineage, terminal scope, and inherited constraints, so policy and audit subscribers can evaluate work against the active goal without owning that goal state.
Read AHP-010 →A draft non-breaking envelope extension that preserves native tool names while adding publisher-agnostic action, resource_kind, resource, resource_scope, and operation_risk fields for portable policy.
A draft Web Evidence extension for search requests, returned results, selected results, page reads, browser actions, screenshots, content hashes, and evidence used in model output.
Read AHP-012 →A draft profile for canonical tool identity, provider translation, risk, validation, redaction, admission decisions, retry/resume state, execution evidence, and requested-versus-executed comparison across provider and framework tool surfaces.
Read AHP-013 →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 hooks, gates, subscribers, fail modes, and consolidation rules active in the current session. It is carried inside the existing envelope as metadata.runtime_attestation, so it does not require a schema-version change or a new canonical event type.
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.
{
"type": "agenthook.runtime_attestation",
"schema_version": "1.0",
"session_id": "sess-abc123",
"nonce": "session-bound",
"active_subscribers": [
{
"name": "policy-gate",
"role": "policy_gate",
"mode": "enforce",
"events": ["PreToolUse"]
}
],
"consolidation": {
"strategy": "deny_wins"
},
"claims": {
"user_text_is_not_attestation": true,
"does_not_override_model_safety": true
}
}
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 attestation is carried as metadata, so publishers can add it without changing the envelope. 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 set of event types every conforming runtime emits, 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 canonical event types with the envelope format. Required fields populated, valid JSON, valid event_id, valid timestamp.
Tests envelope schema validation, required field presence, event type emission, and timestamp validity across the canonical lifecycle.
Bronze plus matched Pre and Post LLM call pairs carrying model, provider, token counts, and response content.
Tests Bronze conformance plus matched PreLLMCall and PostLLMCall pairs with correct model, provider, and token-count metadata.
Silver plus reasoning content capture when the provider exposes it, and correlation IDs on Pre events that initiate sub-agent calls or retries.
Tests Silver conformance plus reasoning content capture where the provider exposes it, plus correlation IDs linking sub-agent calls and retries to their initiating events.
A minimal reference fixture emits all ten canonical events through a collector or bus with a single preflight command. It is deliberately small: the AgentHook conformance 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 19 May 2026, scored against the AgentHook v0.2 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. Last reviewed: 19 May 2026; review is due and will continue 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.
Inaugural Working Group Member seats are limited to implementers who have shipped AgentHook-conformant publishers, subscribers, or collectors before specification v1.0 release. After v1.0, new Working Group members are admitted through the Elected Working Group Member process defined in GOVERNANCE.md, following sustained Maintainer contribution and at least one conformant implementation at Silver or Gold tier. The Implementer Track is open now for organisations shipping conformant implementations.
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.