Composition and failure

Control decisions must be deterministic. AHP makes interceptor order, timeout behavior, and failure handling part of the protocol rather than leaving them to each vendor.

Interceptor order

The portable registration document uses an ordered hooks array. For a given event, the harness evaluates matching interceptors serially in array order:

1. The harness sends hooks/intercept.
2. If the result has no effects, the harness proceeds to the next interceptor.
3. If the result contains deny, the harness stops the chain and denies the operation.
4. If an operational failure occurs under fail-open, the harness records the failure locally and proceeds to the next interceptor.
5. If an operational failure occurs under fail-closed, the harness stops the chain and denies the operation.

This order is normative; harnesses do not run interceptors concurrently in v0.1. Serial order is easy to explain and test, avoids races between denials, and prepares for future mutation effects where each backend may need to see the prior backend’s accepted changes.

Observer delivery never delays the interceptor chain or tool execution; a harness may dispatch observer notifications concurrently. A registration document must not configure the same backend more than once for the same event and mode — ambiguous duplicates are rejected at configuration load time.

Failure classes

The following are operational failures:

• Deadline exceeded
• Connection refused, reset, or lost
• Backend process launch failure or abnormal exit
• Non-success HTTP response
• Malformed UTF-8, JSON, or JSON-RPC
• Mismatched JSON-RPC request and response IDs
• JSON-RPC error response
• Unsupported protocol version or event
• Missing required result fields
• Unadvertised, unknown, malformed, or conflicting effects
• Backend response received after the deadline

An explicit deny is not an operational failure.

Failure policy

Each intercept subscription explicitly configures one of:

• fail-open — continue unchanged after an operational failure.
• fail-closed — deny the operation after an operational failure.

There is no implicit default: requiring an explicit value prevents a security-sensitive deployment from inheriting an unexpected default. Observe subscriptions are always non-blocking and effectively fail open.

For a fail-closed operational failure, the harness presents a generic local reason such as “Required policy backend unavailable” rather than exposing network details, credentials, or malformed backend content to the model. A synthetic denial generated by fail-closed behavior stays distinguishable in local audit records from an explicit backend denial.

Deadlines

Every intercept subscription specifies timeoutMs as a positive integer. The harness enforces the timeout across connection setup, request transmission, backend processing, and response parsing. Values from 100 ms through 30,000 ms should be supported; deployments should pick the smallest value compatible with the backend, because interception sits on the agent’s critical path. When the deadline expires, later responses are ignored and failure policy applies.

Retries and duplicate delivery

A harness may retry an intercept request only while the original deadline remains active. Every retry reuses the same event ID, JSON-RPC ID, session ID, call ID, and event contents. A backend should treat repeated event IDs from the same source as duplicate delivery and return the same semantic result, using (source, event.id) as an idempotency key for side effects. A harness never retries an explicit denial or a successful empty-effect response.

JSON-RPC errors

Backends use standard JSON-RPC error responses. AHP reserves these server-error codes:

Code	Name	Meaning
-32001	unsupported_protocol_version	Backend does not support params.protocolVersion.
-32002	unsupported_event	Backend does not support the supplied event type in this method.
-32003	backend_unavailable	Backend is temporarily unable to evaluate the request.
-32004	backend_internal_error	Backend failed while evaluating the request.

{
  "jsonrpc": "2.0",
  "id": "evt_01JQ8Z2Y6YR0H8N7Q2M3X4V5W6",
  "error": {
    "code": -32001,
    "message": "Unsupported AHP protocol version",
    "data": { "supported": ["0.1"] }
  }
}

Any JSON-RPC error is an operational failure handled by the subscription’s failure policy, and error data must not contain secrets.