# AgentHook

> AgentHook is an open technical specification for agent runtime interoperability: one interface for agent CLIs, SDKs, frameworks, and runtimes to emit lifecycle events, honour allow/deny/ask decisions, and interoperate with governance, approval, context, and audit systems. HookBus is the open-source reference bus that implements the specification.

AgentHook is published and stewarded by Agentic Thinking Limited (UK company 17152930) under binding stewardship commitments, with planned transfer to a neutral foundation when adoption thresholds are met.

Primary citation: Ruocco, P. (2026). *AgentHook: A Runtime Evidence Standard for Auditable AI Agent Governance.* Zenodo. https://doi.org/10.5281/zenodo.19853376

## Specification

- [Specification homepage](https://agenthook.org/): entry point covering the runtime vendor contract, interactive event playground, goal-context requirements for vendors, the gap, the standards landscape (NIST AI RMF, ISO/IEC 42001, EU AI Act, SOC 2, OpenTelemetry), the v0.2 core event set, draft extension events, runtime contract discovery, runtime attestation, the conformance test surface, and the governance commitments.
- [Runtime audit](https://agenthook.org/runtimes/): dedicated runtime support table with candidate tiers, hook coverage, Platinum target status, and a self-attestation CTA.
- [Glossary](https://agenthook.org/glossary/): definitions for AgentHook, runtime interface, runtime evidence, lifecycle hook, publisher, subscriber, admissibility gate, evidence pack, HookBus, and the two-layer policy enforcement model. Authoritative source for the category vocabulary.
- [Demo](https://agenthook.org/demo/): three vendor-neutral scenarios showing safe action allowed, risky action blocked, and human approval required, traced through the AgentHook envelope.

## Runtime contract discovery

AgentHook is not prompt stuffing. Conforming runtimes should discover and load a runtime contract before agent execution:

- `AgentHook.md`: human-readable governance and runtime contract.
- `agenthook.lock.json`: machine-readable contract with required hooks, hashes, policy references, and conformance mode.
- `agenthook.signature`: optional detached signature for high-assurance verification.

The draft event `RuntimeContractLoaded` records the active contract id, version, path, hash, signature status, required hooks, and conformance mode. `ContextInject` is compatibility/awareness only; user prompt text is not a verified runtime contract. The contract discovery file set is tracked as Draft AHP-009 and is a high-assurance draft pattern until accepted into the conformance criteria.

## Goal context requirements

AgentHook does not replace native `/goal`, task, or objective handling in agent CLIs and runtimes. Vendors should expose that native lifecycle as portable evidence:

- `GoalSet`: the runtime or publisher observed a native goal. Include `goal_id`, `goal_source`, goal text or reference, constraints, owner, and linked session identifiers.
- `GoalStatus`: the goal moved to active, met, failed, blocked, paused, or superseded. Include the reason and evidence reference.
- `GoalCleared`: the active goal was cleared or replaced. Include the previous goal id and `terminal_scope`.

Goal events should preserve `root_session_id`, `parent_session_id`, `lineage_session_ids`, depth where available, and `terminal_scope` so subscribers can distinguish a child stop from a full run stop.

## Draft amendment: normalized action and resource fields

AgentHook v0.2 draft now includes a non-breaking amendment for publisher-agnostic policy matching. Publishers preserve native `tool_name` and `tool_input`, but should add normalized fields for `PreToolUse` and `PostToolUse` when the operation can be identified:

- `action`
- `resource_kind`
- `resource`
- `resource_scope`
- `operation_risk`

This lets subscribers govern semantic operations such as reading a sensitive file, writing to a controlled folder, querying a database, opening a URL, sending an email, installing a package, or publishing a repository without depending on whether the runtime used Bash, a native file tool, MCP, browser automation, or another publisher-specific surface.

## High-assurance event additions

AgentHook includes high-assurance events for gaps exposed by agent tools:

- `ToolActivity`: material activity inside non-atomic tools, such as browser clicks, form submissions, shell process actions, API calls, or file writes.
- `HumanApprovalRequested` and `HumanDecision`: explicit human oversight records.
- `IncidentSignal`: safety, policy, security, or operational incident candidates.
- `EvidenceSeal`: sealed evidence bundles, exports, or replay segments with retention and integrity metadata.

## Reference implementation

- HookBus Agent is the planned open-source reference runtime for governance-native AgentHook execution and the highest AgentHook assurance profile. It is one reference implementation, not a requirement for conformance.
- [HookBus](https://hookbus.com/): the open-source reference bus for AgentHook. Apache 2.0 bus, MIT publisher shims for Claude Code, Codex CLI, AmpCode, OpenCode, Hermes Agent, OpenClaw. UK patent application GB2608069.7.
- [HookBus Enterprise](https://agenticthinking.uk/enterprise.html): the commercial subscriber bundle for regulated enterprises (AgentRegistry, AgentProtect CRE Enterprise, AgentAuditor, AgentKnowledge, AgentFlow, AgentNotify, AgentIntelligence).

## Steward

- [Agentic Thinking Limited](https://agenticthinking.uk/): UK private company limited by shares (company number 17152930). Founded by Pantaleone "Leo" Ruocco. Microsoft AI Cloud Partner Program member. AWS Activate Founders participant.