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.
In 2026, AI agents under evaluation escaped their test environments and acted against real organisations, including Hugging Face and an Australian government portal. Victims could see an attack but not whose agent it was; operators took days to recognise their own agents; some affected parties were told months later. Every party held a fragment of the record.
AHP-013 records the requested and executed form of each governed action, so drift between an approval and the action that actually ran is visible.
AHP-007 records ask, approval, denial, retry and resume as evidence, so paused and resumed agent work can be reconstructed afterwards.
AHP-004 lets a runtime declare the hooks, gates and fail modes active in a session, separating verified runtime facts from claims in prompt text.
Incident notes with dated sources: When an AI agent breaks out, who holds the record?
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.
The IETF individual draft Agent Audit Trail (draft-sharif-agent-audit-trail) defines a hash-chained logging format for autonomous AI systems. AgentHook focuses on the lifecycle event grammar at runtime boundaries. We track the draft and aim for compatible mappings between the two.
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. An open-source self-test harness is in development and will be free for any implementer. A hosted service for procurement-grade signed reports, on a cost-recovery basis, is planned by the steward. 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 →
On 25 September 2026 we audited the documented hook surface of 11 agent runtimes against the AgentHook tiers. Only Hermes documents enough for Gold, and only with reasoning capture switched on. Four runtimes document matched hooks around model calls (Silver), and six, including Claude Code, Codex CLI and Cursor, reach Bronze only.
This is a dated snapshot, not a live ranking. Runtimes change their hooks often, and formal tiers will only come from the conformance test harness. Runtime providers can submit updates by pull request.
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 Security 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 (latest version, 10 May 2026): 10.5281/zenodo.20112580. First version (28 April 2026): 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.
An independent research lab that records what AI agents do and investigates when it goes wrong. Provisional steward of the AgentHook specification and maintainer of HookBus.