Agent Hook Spec

Agent Hook Spec is a community effort to define a portable lifecycle-hook protocol for AI agents and their tooling. It will let agent builders describe events, hook payloads, hook responses, and security telemetry using a shared, interoperable model.

The revised 0.1 draft defines eighteen canonical Core hook_event_name values across session and turn lifecycle, user prompts, model requests and responses, tool use, permission outcomes, subagent delegation, application network requests, durable memory writes, and configuration changes. Hosts publish the Core boundaries and gate behavior they can observe and enforce faithfully. Each per-event capability claim is gate, observe, partial, or unavailable; an unavailable claim is not evidence that the underlying activity did not occur.

Status

The repository contains an adoption-ready Agent Hook 0.1 draft proposed by RFC 0001, with five additional standard events proposed by RFC 0004. It is not active until accepted through the RFC process. Join the GitHub Discussions to help shape it.

Repository map

• rfcs/ — proposal process and formal RFCs.
• spec/ — canonical normative specification Markdown.
• schemas/ — machine-readable JSON Schemas.
• fixtures/ — schema-validation fixtures.
• examples/ — illustrative integrations.
• website/ — Docusaurus source for the GitHub Pages site.

Local setup

Use Node.js 20 or later; CI validates and builds with Node.js 24. From the repository root, install the validator and website dependencies separately:

npm ci
npm ci --prefix website

Validate the schemas and fixtures, then build the website:

npm run validate
npm run build

To preview the website locally, run:

npm start

Participate

Read CONTRIBUTING.md before contributing. The decision process, voting rules, and RFC lifecycle are defined in GOVERNANCE.md. For sensitive matters, follow SECURITY.md.

Keep the website in sync

Every pull request must review its website impact and update affected website content in the same PR. Follow the website synchronization checklist for canonical spec pages, site summaries, and published schema copies. Explain the website updates in the PR, or why no website change is needed.

Licenses

Specifications and documentation are licensed under CC BY 4.0. Code, schemas, tooling, and website assets are licensed under the MIT License.