Agent Hooks ProtocolWorking Draft · draft

Open protocol · Working Draft

Portable control points for agent actions

The Agent Hooks Protocol (AHP) defines a vendor-neutral boundary between agent harnesses and policy, security, approval, and runtime middleware. It lets a harness expose agent actions to portable backends before side effects occur, without replacing the harness's own permissions, approvals, or sandbox.

Get started Read the specification

An admission-control boundary for agent operations

Before a tool call executes, the harness emits a canonical tool.beforeevent through hooks/intercept. Each configured backend returns either no effect or one explicit deny. The harness stays the execution and security boundary: it enforces deadlines, failure policy, and its own permissions.

AHP interception at the harness boundaryAn agent asks its harness to run a tool. The harness evaluates each configured AHP backend serially and outside its boundary. When no backend denies, the harness applies its own permissions and executes the tool itself, inside its boundary. When any backend denies, evaluation stops, later backends are never reached, and the tool never runs.HARNESS · AHP CLIENTtrust and execution boundaryAgentwants to run a toolInterception pointemits tool.before · hooks/interceptHOOK BACKENDS · AHP SERVERS1policy engine2DLP scanner3approvalevaluated in order · stops on a denyharness permissionsTool runtimethe harness runs the call itselfexecuting Bashnever invoked

1/8The agent asks its harness to run a tool.

Backends never execute anything — each returns either no effect or one explicit deny. The harness stays the execution and security boundary.

Plain JSON-RPC on the wire

AHP uses UTF-8 JSON-RPC 2.0 over newline-delimited stdio or bounded HTTP POST. Every request is self-describing: it carries the protocol version and the exact effects the harness can enforce, so backends never infer behavior from a vendor name.

{
  "jsonrpc": "2.0",
  "id": "evt_01JQ8Z2Y6YR0H8N7Q2M3X4V5W6",
  "method": "hooks/intercept",
  "params": {
    "protocolVersion": "draft",
    "event": {
      "type": "tool.before",
      "session": { "id": "sess_123" },
      "tool": {
        "callId": "call_456",
        "name": "Bash",
        "kind": "shell",
        "input": { "command": "git push --force" }
      }
    },
    "capabilities": { "effects": ["deny"] }
  }
}

Explore the documentation

Informative guides to the Working Draft, organized by protocol concern.

Architecture

Roles, the JSON-RPC protocol model, versioning, and unknown-field rules.

Events

The canonical envelope, session and tool identity, and the event lifecycle.

Capabilities and effects

Explicit capability advertisement, the deny effect, and why there is no allow.

Composition and failure

Deterministic interceptor ordering, deadlines, fail-open and fail-closed policy.

Transports

The stdio and HTTP bindings, framing rules, TLS, and bearer authentication.

Registration

The portable document that configures backends, subscriptions, and failure policy.

Where AHP fits

AHP complements existing agent standards; it does not replace tool connectivity, client–agent communication, agent collaboration, or observability.

ProtocolConnects
MCPAgents and clients to tools, resources, and context providers.
ACPEditors and clients to coding agents.
A2AAgents to other agents.
AHPAn agent harness to external runtime-control middleware.

Status: Working Draft

AHP is at an early stage. All current protocol artifacts are Working Drafts (draft) and are not a stable compatibility commitment. Thecanonical specification in theagent-hooks-protocol repository is the normative source; this site is an informative companion.

The draft ships with versioned JSON Schemas,golden fixtures,conformance profiles, and a publicproposal process. Implementation experience and review feedback are welcome.