Reasonix Extension Protocol v2

September 4, 2026 · View on GitHub

Protocol ID: reasonix.extension.v2
Protocol major: 2
Schema: internal/extension/protocol/schema.generated.json
Schema hash: sha256:ac99dbabd4f6e354c89aced778d8a83646e7a06345cc67d08bcb3faf73bb56f5

Within major v2 only optional fields, new enum values, and new methods may be added; existing required fields, directions, limits, error reasons, and semantics never change.

Methods

Method	Direction	Class	Params	Result
`extension/event`	`host_to_extension_notification`	`observation`	`EventParams`	`-`
`extension/initialize`	`host_to_extension_request`	`lifecycle`	`InitializeParams`	`InitializeResult`
`extension/initialized`	`host_to_extension_notification`	`lifecycle`	`InitializedParams`	`-`
`extension/intercept`	`host_to_extension_request`	`intercept`	`InterceptParams`	`InterceptResult`
`extension/provider/catalog`	`host_to_extension_request`	`provider`	`ProviderCatalogParams`	`ProviderCatalogResult`
`extension/provider/stream/cancel`	`host_to_extension_request`	`provider`	`StreamCancelParams`	`StreamCancelResult`
`extension/provider/stream/chunk`	`extension_to_host_notification`	`provider`	`StreamChunkParams`	`-`
`extension/provider/stream/end`	`extension_to_host_notification`	`provider`	`StreamEndParams`	`-`
`extension/provider/stream/open`	`host_to_extension_request`	`provider`	`StreamOpenParams`	`StreamOpenResult`
`extension/resources/changed`	`host_to_extension_notification`	`observation`	`ResourcesChangedParams`	`-`
`extension/shutdown`	`host_to_extension_request`	`lifecycle`	`ShutdownParams`	`ShutdownResult`
`extension/ui/action`	`host_to_extension_request`	`ui`	`UIActionParams`	`UIActionResult`
`extension/ui/submit`	`host_to_extension_request`	`ui`	`UISubmitParams`	`UISubmitResult`
`host/content/read`	`extension_to_host_request`	`content`	`ContentReadParams`	`ContentReadResult`
`host/ui/publish`	`extension_to_host_request`	`ui`	`UIPublishParams`	`UIPublishResult`
`host/ui/request`	`extension_to_host_request`	`ui`	`UIRequestParams`	`UIRequestResult`

Intercept events (17)

extension/intercept (blocking) and extension/event (observation) share these frozen hook points:

agent.before_start
compaction.complete
compaction.prepare
context.prepare
frontend.event
input.receive
permission.decision
provider.request
provider.response
session.end
session.load
session.rotate
session.save
session.start
system_prompt.build
tool.after
tool.before

Limits

Limit	Value
`frameBytes`	8388608
`externalizeFieldBytes`	65536
`contentRefChunkBytes`	262144
`contentRefObjectBytes`	8388608

Errors

Reason	JSON-RPC code	Retryable	Message
`activation_failed`	-32000	false	Component activation failed; the new generation was not published.
`capability_not_declared`	-32000	false	The extension used a capability its manifest did not declare.
`cleanup_failed`	-32000	true	Component cleanup failed while disposing scoped effects.
`content_ref_expired`	-32000	true	The referenced content has expired.
`dependency_cycle`	-32000	false	The dependency graph contains a required cycle.
`dependency_unsatisfied`	-32000	false	A required dependency is missing or not version-compatible.
`frame_too_large`	-32000	false	The frame exceeds the frozen protocol size limit.
`intercept_timeout`	-32000	true	The extension did not answer an intercept within its timeout.
`internal`	-32603	true	An internal extension protocol error occurred.
`invalid_params`	-32602	false	The params do not match the registered method schema.
`protocol_error`	-32600	false	The extension protocol frame or envelope is invalid.
`provider_failed`	-32000	true	The extension provider stream failed.
`provider_interrupted`	-32000	true	The extension provider stream was interrupted.
`schema_mismatch`	-32000	false	A capability schema hash does not match the expected pin.
`shutdown_timeout`	-32000	true	The extension did not shut down within the requested timeout.
`stale_generation`	-32000	false	The message belongs to a superseded runtime generation.
`stream_cancelled`	-32000	false	The provider stream was cancelled.
`stream_gap`	-32000	true	A provider stream chunk is missing from the ordered sequence.
`unknown_method`	-32601	false	The method is not registered in Extension Protocol v2.
`unsupported_version`	-32000	false	The peer's extension protocol version is not supported.