Protocol model and versioning
Protocol model
JSON-RPC
AHP-RPC-001 — MUST. Protocol messages use UTF-8 JSON-RPC 2.0.
AHP-RPC-002 — MUST. An interception that expects a decision uses a hooks/intercept request; one-way observation uses a hooks/observe notification.
AHP uses JSON-RPC 2.0. All messages MUST be UTF-8 encoded. This protocol revision defines three methods:
| Method | JSON-RPC type | Requirement | Purpose |
| `hooks/intercept` | Request | Tool Interception profile | Ask a backend for effects before continuing an operation. |
| `hooks/observe` | Notification | Lifecycle Observation profile | Deliver a one-way lifecycle event. |
| `hooks/capabilities` | Request | Harness capability discovery | Read the manifest independently of session creation; see [discovery](/docs/spec/draft/capability-auth/). |
AHP-VER-001 — MUST. Every request, notification, and successful result carries protocolVersion equal to its protocol snapshot identifier.
Every AHP params object and every successful result MUST contain protocolVersion equal to the selected protocol snapshot identifier. The mutable working snapshot uses the literal identifier draft on the wire. Publication assigns the release date in YYYY-MM-DD form to the copied snapshot, its schemas and manifests, and every on-wire protocolVersion.
For a request, a receiver that does not support the supplied version MUST return the AHP JSON-RPC error unsupported_protocol_version. A notification never receives a JSON-RPC response, including on version mismatch; the receiver MUST NOT process unsupported semantics. Because process-per-event backends cannot rely on a prior handshake, version and capabilities are carried on each intercept request. Implementations use exact-version matching; date ordering does not imply wire compatibility.
Unknown fields
AHP-CORE-003 — MUST. Receivers ignore unknown configuration and envelope fields, validate recognized fields, and reject unknown effect fields atomically; unknown fields do not alter core semantics.
Receivers MUST ignore unknown fields in otherwise valid configuration, authentication, capability, upload, control-state, and protocol envelope objects, and MUST validate recognized fields. Effect objects are strict: unknown fields MUST reject the whole response atomically. Senders MUST NOT infer that an ignored optional field changed backend behavior. Unknown event types, effect types, and enum values are not ordinary unknown fields. They MUST be handled as unsupported protocol semantics.
JSON values
Fields described as JSON objects MUST contain objects, not encoded JSON strings. Tool input and output MAY contain any valid JSON values only where explicitly allowed by their event schema.