Agent Hooks Protocol
Status: Working Draft (draft)
Canonical specification: This document
This is the canonical, language-neutral Agent Hooks Protocol specification. The Base Protocol, Server Features, and compatibility-adapter requirements are normative where they use BCP 14 terms; the abstract, rationale, open questions, and references are informative. JSON Schemas constrain representable JSON shape; this prose defines protocol semantics. A conflict between prose, schemas, requirements, and fixtures is a specification defect, not permission to choose whichever behavior is convenient.
Protocol version: draft
Audience: Agent-harness implementers, compatibility-adapter authors, and policy, security, approval, and runtime-middleware vendors
Specification map
- Architecture
- Base Protocol
- Server Features
- Client Features
- Execution payloads
- Interaction and MCP elicitation payloads
- Task, workspace, and lineage semantics
- Observation delivery
- Canonical inline messages, content selection, and attachment uploads
- Capabilities, registration, and authentication
- Design rationale and references
- Open questions
- Changelog
Abstract
The Agent Hooks Protocol (AHP) defines a vendor-neutral interface through which an agent harness can ask an external backend to inspect and control an impending runtime operation. This draft defines capability-advertised lifecycle and operation boundaries, atomic compound effects, content delivery, and registration over stdio and HTTP. Implementations advertise the events, modes, targets, and operations they can faithfully support; the schema catalogue does not require every harness to implement every boundary. AHP is primarily a control-plane protocol. AHP provides an optional one-way notification mode for control-adjacent audit and compatibility use cases, but observation is not required for minimum conformance to this protocol revision. Observations do not make decisions; their delivery is owned by the enclosing hook call and may contribute to its completion latency. See observation delivery and composition.
Status of this document
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals.