agenthooksprotocol 0.8.0__tar.gz → 0.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. {agenthooksprotocol-0.8.0/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.9.0}/PKG-INFO +4 -2
  2. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/README.md +3 -1
  3. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/pyproject.toml +1 -1
  4. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_hooks.py +15 -0
  5. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/ahp-codegen.lock.json +1 -1
  6. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0/src/agenthooksprotocol.egg-info}/PKG-INFO +4 -2
  7. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_event_types.py +1 -0
  8. agenthooksprotocol-0.9.0/tests/test_subscribes.py +177 -0
  9. agenthooksprotocol-0.8.0/tests/test_subscribes.py +0 -76
  10. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/LICENSE +0 -0
  11. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/setup.cfg +0 -0
  12. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/__init__.py +0 -0
  13. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_boundaries.py +0 -0
  14. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_content.py +0 -0
  15. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_diagnostics.py +0 -0
  16. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_elicitation.py +0 -0
  17. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_grants.py +0 -0
  18. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_host_metadata.py +0 -0
  19. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_interop_content.py +0 -0
  20. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_interop_hooks.py +0 -0
  21. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/__init__.py +0 -0
  22. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/capability.py +0 -0
  23. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/content.py +0 -0
  24. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/effect.py +0 -0
  25. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/event.py +0 -0
  26. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/registration.py +0 -0
  27. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/subscription.py +0 -0
  28. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/tool.py +0 -0
  29. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/transport.py +0 -0
  30. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_outcomes.py +0 -0
  31. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_validator.py +0 -0
  32. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/attachment.py +0 -0
  33. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/auth.py +0 -0
  34. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/candidate.py +0 -0
  35. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/capability.py +0 -0
  36. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/catalogue.py +0 -0
  37. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/codec.py +0 -0
  38. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/compaction.py +0 -0
  39. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/content.py +0 -0
  40. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/contract.py +0 -0
  41. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/diagnostics.py +0 -0
  42. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/effect.py +0 -0
  43. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/elicitation.py +0 -0
  44. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/event.py +0 -0
  45. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/generated.py +0 -0
  46. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/headers.py +0 -0
  47. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/integrations/__init__.py +0 -0
  48. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/integrations/pydantic.py +0 -0
  49. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/interop.py +0 -0
  50. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle.py +0 -0
  51. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle_client.py +0 -0
  52. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle_server.py +0 -0
  53. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lineage.py +0 -0
  54. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/observation_chain.py +0 -0
  55. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/path.py +0 -0
  56. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/permission.py +0 -0
  57. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/py.typed +0 -0
  58. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/registration.py +0 -0
  59. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/response.py +0 -0
  60. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/runtime.py +0 -0
  61. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/schemas.json +0 -0
  62. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/__init__.py +0 -0
  63. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_admission.py +0 -0
  64. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_framing.py +0 -0
  65. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_handlers.py +0 -0
  66. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_json.py +0 -0
  67. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_slots.py +0 -0
  68. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/asgi.py +0 -0
  69. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/attachments.py +0 -0
  70. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/hooks.py +0 -0
  71. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/stdio.py +0 -0
  72. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/state.py +0 -0
  73. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/subscription.py +0 -0
  74. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/tool.py +0 -0
  75. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transport.py +0 -0
  76. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/__init__.py +0 -0
  77. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/http.py +0 -0
  78. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/stdio.py +0 -0
  79. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/wire.py +0 -0
  80. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/SOURCES.txt +0 -0
  81. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/dependency_links.txt +0 -0
  82. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/requires.txt +0 -0
  83. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/top_level.txt +0 -0
  84. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_attachments.py +0 -0
  85. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_catalogue.py +0 -0
  86. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_codec.py +0 -0
  87. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_compaction.py +0 -0
  88. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_compaction_wire.py +0 -0
  89. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_consumer_outcomes.py +0 -0
  90. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_content.py +0 -0
  91. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_content_lifetime.py +0 -0
  92. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_content_receipts.py +0 -0
  93. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_correlated_core.py +0 -0
  94. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_declared_contracts.py +0 -0
  95. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_elicitation_adapter.py +0 -0
  96. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_fixture_public.py +0 -0
  97. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_handwritten_surface.py +0 -0
  98. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_harness_identity.py +0 -0
  99. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_host_metadata.py +0 -0
  100. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_inline_messages.py +0 -0
  101. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_integration.py +0 -0
  102. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_integration_edges.py +0 -0
  103. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_interop.py +0 -0
  104. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_lifecycle.py +0 -0
  105. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_lifecycle_auth.py +0 -0
  106. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_observation.py +0 -0
  107. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_observation_chain_transport.py +0 -0
  108. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_owned_content.py +0 -0
  109. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_owned_content_hooks.py +0 -0
  110. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_package.py +0 -0
  111. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_public_content.py +0 -0
  112. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_public_contract_surface.py +0 -0
  113. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_public_examples.py +0 -0
  114. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_public_hooks.py +0 -0
  115. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_public_server.py +0 -0
  116. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_registration_auth.py +0 -0
  117. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_registration_headers.py +0 -0
  118. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_safety.py +0 -0
  119. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_schema_corrections.py +0 -0
  120. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_sdk_unification.py +0 -0
  121. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_server_catch_all.py +0 -0
  122. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_server_error_codes.py +0 -0
  123. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_session_manifest.py +0 -0
  124. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_shared_materialization.py +0 -0
  125. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_stdio_env.py +0 -0
  126. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_stdio_transport.py +0 -0
  127. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_structural_facade.py +0 -0
  128. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_typed_capabilities.py +0 -0
  129. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_typed_contract_regressions.py +0 -0
  130. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_upload_planning.py +0 -0
  131. {agenthooksprotocol-0.8.0 → agenthooksprotocol-0.9.0}/tests/test_validator_optimization.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agenthooksprotocol
3
- Version: 0.8.0
3
+ Version: 0.9.0
4
4
  Summary: Official non-normative Python SDK for the Agent Hooks Protocol
5
5
  Author: Agent Hooks Protocol maintainers
6
6
  License:
@@ -269,7 +269,7 @@ async def review(existing_arguments):
269
269
  return result # Host validation and authorization still precede execution.
270
270
  ```
271
271
 
272
- Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
272
+ Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, `intercepts`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
273
273
 
274
274
  Host capabilities are frozen, keyword-only dataclasses; there are no builder functions. Each event has its own `<Event>Capabilities` declaration. Events that support interception take `intercept=<Event>Intercept(...)` grants, and every declaration takes `observe`, which defaults to `False`, so to advertise both modes you must pass `observe=True` explicitly. Observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. `modify_input=capability.Modify.REPLACE` supplies both the effect grant and its operation block, and form/URL elicitation grants are explicit (`elicitation=capability.Elicitation.FORM`, `URL`, or `FORM_AND_URL`). Interception without a control grant and declarations with neither mode are rejected at construction; boundary compatibility is validated before delivery. Omission never implies permission. Per-call `capabilities=` only narrows configured grants.
275
275
 
@@ -364,6 +364,8 @@ Registered stdio backends start with a minimal base environment rather than the
364
364
 
365
365
  `hooks.subscribes("tool.before")` is a pure synchronous static-interest lookup. Use it before expensive input preparation: `False` means no eligible intercept or observe subscription selects the configured event. Exact selectors, `*`, and prefix selectors such as `tool.*` use the same matching as dispatch. Unknown or unconfigured events return `False`. Payload filters are conservatively ignored, so `True` means potential interest, not permission or guaranteed delivery. The lookup does not prepare input, authenticate, upload content, initialize transports, or contact backends.
366
366
 
367
+ `hooks.intercepts("model.response.after")` is `subscribes` restricted to intercept subscriptions. Use it to decide whether to withhold streamed output until interceptors settle.
368
+
367
369
  Configure `Hooks(config, *, source, harness=event.Harness(name="example", version="1"), capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. The required `source`, `harness`, and `capabilities` configure one host. Harness name and version identify the emitter on every event; SDK-generated events use a detached snapshot of that identity. Typed host capabilities are the sole source of event modes and effect grants. Optional metadata declares transport/authentication facilities, tool paths, content categories, limits, managed policy, gaps, correlation fields, and opaque extras without granting event authority. Metadata cannot contain events or override known fields through extras. `hooks.manifest` returns a detached canonical snapshot.
368
370
 
369
371
  The frozen, keyword-only host capability model advertises only explicitly declared events and modes. Each event has its own declaration type: `ToolBeforeCapabilities(intercept=..., observe=True)` accepts typed interception options and an observation flag, while observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. Empty declarations, empty interception, and invalid option values are rejected at construction, while an empty `HostCapabilities()` grants nothing and elicitation-only interception is a valid facility declaration. `Modify.REPLACE`, `Modify.MERGE`, and `Modify.REPLACE_AND_MERGE` declare complete modification grants. `HostCapabilities.to_wire()` returns fresh canonical declarations directly; it does not parse JSON. Runtime admission still validates registration, request-time grants, and responses. The derived manifest records gaps for omitted events and host-level facilities not supplied through metadata. Explicit empty metadata collections declare no such facility; they do not mean universal support.
@@ -45,7 +45,7 @@ async def review(existing_arguments):
45
45
  return result # Host validation and authorization still precede execution.
46
46
  ```
47
47
 
48
- Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
48
+ Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, `intercepts`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
49
49
 
50
50
  Host capabilities are frozen, keyword-only dataclasses; there are no builder functions. Each event has its own `<Event>Capabilities` declaration. Events that support interception take `intercept=<Event>Intercept(...)` grants, and every declaration takes `observe`, which defaults to `False`, so to advertise both modes you must pass `observe=True` explicitly. Observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. `modify_input=capability.Modify.REPLACE` supplies both the effect grant and its operation block, and form/URL elicitation grants are explicit (`elicitation=capability.Elicitation.FORM`, `URL`, or `FORM_AND_URL`). Interception without a control grant and declarations with neither mode are rejected at construction; boundary compatibility is validated before delivery. Omission never implies permission. Per-call `capabilities=` only narrows configured grants.
51
51
 
@@ -140,6 +140,8 @@ Registered stdio backends start with a minimal base environment rather than the
140
140
 
141
141
  `hooks.subscribes("tool.before")` is a pure synchronous static-interest lookup. Use it before expensive input preparation: `False` means no eligible intercept or observe subscription selects the configured event. Exact selectors, `*`, and prefix selectors such as `tool.*` use the same matching as dispatch. Unknown or unconfigured events return `False`. Payload filters are conservatively ignored, so `True` means potential interest, not permission or guaranteed delivery. The lookup does not prepare input, authenticate, upload content, initialize transports, or contact backends.
142
142
 
143
+ `hooks.intercepts("model.response.after")` is `subscribes` restricted to intercept subscriptions. Use it to decide whether to withhold streamed output until interceptors settle.
144
+
143
145
  Configure `Hooks(config, *, source, harness=event.Harness(name="example", version="1"), capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. The required `source`, `harness`, and `capabilities` configure one host. Harness name and version identify the emitter on every event; SDK-generated events use a detached snapshot of that identity. Typed host capabilities are the sole source of event modes and effect grants. Optional metadata declares transport/authentication facilities, tool paths, content categories, limits, managed policy, gaps, correlation fields, and opaque extras without granting event authority. Metadata cannot contain events or override known fields through extras. `hooks.manifest` returns a detached canonical snapshot.
144
146
 
145
147
  The frozen, keyword-only host capability model advertises only explicitly declared events and modes. Each event has its own declaration type: `ToolBeforeCapabilities(intercept=..., observe=True)` accepts typed interception options and an observation flag, while observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. Empty declarations, empty interception, and invalid option values are rejected at construction, while an empty `HostCapabilities()` grants nothing and elicitation-only interception is a valid facility declaration. `Modify.REPLACE`, `Modify.MERGE`, and `Modify.REPLACE_AND_MERGE` declare complete modification grants. `HostCapabilities.to_wire()` returns fresh canonical declarations directly; it does not parse JSON. Runtime admission still validates registration, request-time grants, and responses. The derived manifest records gaps for omitted events and host-level facilities not supplied through metadata. Explicit empty metadata collections declare no such facility; they do not mean universal support.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "agenthooksprotocol"
7
- version = "0.8.0"
7
+ version = "0.9.0"
8
8
  description = "Official non-normative Python SDK for the Agent Hooks Protocol"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -795,6 +795,21 @@ class Hooks(BoundaryMixin):
795
795
  for subscription in backend["subscriptions"]
796
796
  )
797
797
 
798
+ def intercepts(self, event: EventType) -> bool:
799
+ """Report whether any intercept subscription the host granted selects the event.
800
+
801
+ Payload-dependent filters are not evaluated.
802
+ """
803
+ declaration = self.capabilities.get(event)
804
+ if declaration is None or "intercept" not in declaration["modes"]:
805
+ return False
806
+ return any(
807
+ subscription["mode"] == "intercept"
808
+ and any(_matches(selector, event) for selector in subscription["events"])
809
+ for backend in self.config["hooks"]
810
+ for subscription in backend["subscriptions"]
811
+ )
812
+
798
813
  @property
799
814
  def manifest(self) -> dict[str, Any]:
800
815
  """Return a detached snapshot of the configured static host manifest."""
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "sourceRepository": "agenthooksprotocol/agent-hooks-protocol",
3
- "sourceCommit": "6e409ee9a1670220cfa79cdc47a6df0be438bd6a",
3
+ "sourceCommit": "6327cb47b15eba7a2ec4bd6c9a32cb19eeabfd3d",
4
4
  "schemaRevision": "draft",
5
5
  "protocolVersion": "draft",
6
6
  "generatorVersion": "0.1.0",
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agenthooksprotocol
3
- Version: 0.8.0
3
+ Version: 0.9.0
4
4
  Summary: Official non-normative Python SDK for the Agent Hooks Protocol
5
5
  Author: Agent Hooks Protocol maintainers
6
6
  License:
@@ -269,7 +269,7 @@ async def review(existing_arguments):
269
269
  return result # Host validation and authorization still precede execution.
270
270
  ```
271
271
 
272
- Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
272
+ Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, `intercepts`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
273
273
 
274
274
  Host capabilities are frozen, keyword-only dataclasses; there are no builder functions. Each event has its own `<Event>Capabilities` declaration. Events that support interception take `intercept=<Event>Intercept(...)` grants, and every declaration takes `observe`, which defaults to `False`, so to advertise both modes you must pass `observe=True` explicitly. Observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. `modify_input=capability.Modify.REPLACE` supplies both the effect grant and its operation block, and form/URL elicitation grants are explicit (`elicitation=capability.Elicitation.FORM`, `URL`, or `FORM_AND_URL`). Interception without a control grant and declarations with neither mode are rejected at construction; boundary compatibility is validated before delivery. Omission never implies permission. Per-call `capabilities=` only narrows configured grants.
275
275
 
@@ -364,6 +364,8 @@ Registered stdio backends start with a minimal base environment rather than the
364
364
 
365
365
  `hooks.subscribes("tool.before")` is a pure synchronous static-interest lookup. Use it before expensive input preparation: `False` means no eligible intercept or observe subscription selects the configured event. Exact selectors, `*`, and prefix selectors such as `tool.*` use the same matching as dispatch. Unknown or unconfigured events return `False`. Payload filters are conservatively ignored, so `True` means potential interest, not permission or guaranteed delivery. The lookup does not prepare input, authenticate, upload content, initialize transports, or contact backends.
366
366
 
367
+ `hooks.intercepts("model.response.after")` is `subscribes` restricted to intercept subscriptions. Use it to decide whether to withhold streamed output until interceptors settle.
368
+
367
369
  Configure `Hooks(config, *, source, harness=event.Harness(name="example", version="1"), capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. The required `source`, `harness`, and `capabilities` configure one host. Harness name and version identify the emitter on every event; SDK-generated events use a detached snapshot of that identity. Typed host capabilities are the sole source of event modes and effect grants. Optional metadata declares transport/authentication facilities, tool paths, content categories, limits, managed policy, gaps, correlation fields, and opaque extras without granting event authority. Metadata cannot contain events or override known fields through extras. `hooks.manifest` returns a detached canonical snapshot.
368
370
 
369
371
  The frozen, keyword-only host capability model advertises only explicitly declared events and modes. Each event has its own declaration type: `ToolBeforeCapabilities(intercept=..., observe=True)` accepts typed interception options and an observation flag, while observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. Empty declarations, empty interception, and invalid option values are rejected at construction, while an empty `HostCapabilities()` grants nothing and elicitation-only interception is a valid facility declaration. `Modify.REPLACE`, `Modify.MERGE`, and `Modify.REPLACE_AND_MERGE` declare complete modification grants. `HostCapabilities.to_wire()` returns fresh canonical declarations directly; it does not parse JSON. Runtime admission still validates registration, request-time grants, and responses. The derived manifest records gaps for omitted events and host-level facilities not supplied through metadata. Explicit empty metadata collections declare no such facility; they do not mean universal support.
@@ -18,6 +18,7 @@ class EventTypeTests(unittest.TestCase):
18
18
  self.assertIs(EventType, EventModuleType)
19
19
  self.assertEqual(len(get_args(EventType)), 32)
20
20
  self.assertIs(get_type_hints(Hooks.subscribes)["event"], EventType)
21
+ self.assertIs(get_type_hints(Hooks.intercepts)["event"], EventType)
21
22
  methods = get_overloads(Hooks.dispatch) + [Hooks.dispatch]
22
23
  self.assertEqual(len(methods), 9)
23
24
  for method in methods:
@@ -0,0 +1,177 @@
1
+ """External public consumer coverage for synchronous static interest."""
2
+
3
+ from agenthooksprotocol import event as protocol_event
4
+ from agenthooksprotocol import capability
5
+
6
+ from copy import deepcopy
7
+ import unittest
8
+ from unittest.mock import patch
9
+
10
+ from agenthooksprotocol import Hooks
11
+ from test_public_hooks import capabilities, config
12
+
13
+
14
+ class SubscriptionInterestTests(unittest.TestCase):
15
+ def test_static_interest(self):
16
+ for mode in ("intercept", "observe"):
17
+ for selector in ("tool.before", "tool.*", "*"):
18
+ for filtered in (False, True):
19
+ with self.subTest(mode=mode, selector=selector, filtered=filtered):
20
+ registration = config(mode=mode)
21
+ subscription = registration["hooks"][0]["subscriptions"][0]
22
+ subscription["events"] = [selector]
23
+ if filtered:
24
+ subscription["filters"] = {
25
+ "toolKinds": ["shell"],
26
+ "paths": ["not-the-path"],
27
+ }
28
+ hooks = Hooks(
29
+ registration,
30
+ source="urn:test",
31
+ harness=protocol_event.Harness(
32
+ name="test-host", version="1"
33
+ ),
34
+ capabilities=capabilities(),
35
+ )
36
+ before = deepcopy((hooks.config, hooks.capabilities))
37
+ with (
38
+ patch.object(
39
+ hooks,
40
+ "_ensure_ready",
41
+ side_effect=AssertionError("transport"),
42
+ ),
43
+ patch.object(
44
+ hooks,
45
+ "_project_delivery",
46
+ side_effect=AssertionError("input preparation"),
47
+ ),
48
+ patch.object(
49
+ hooks.validator,
50
+ "validate",
51
+ side_effect=AssertionError("input validation"),
52
+ ),
53
+ ):
54
+ for _ in range(2):
55
+ self.assertIs(hooks.subscribes("tool.before"), True)
56
+ self.assertIs(hooks.subscribes("tool.after"), False)
57
+ self.assertIs(hooks.subscribes("unknown.event"), False)
58
+ self.assertIs(hooks.subscribes(""), False)
59
+ self.assertEqual((hooks.config, hooks.capabilities), before)
60
+
61
+ def test_no_subscribers_and_unrelated_selectors(self):
62
+ declarations = capability.HostCapabilities(
63
+ tool_before=capabilities().tool_before,
64
+ tool_after=capability.ToolAfterCapabilities(observe=True),
65
+ )
66
+ registration = config(mode="observe")
67
+ registration["hooks"][0]["subscriptions"][0]["events"] = ["tool.after"]
68
+ hooks = Hooks(
69
+ registration,
70
+ source="urn:test",
71
+ harness=protocol_event.Harness(name="test-host", version="1"),
72
+ capabilities=declarations,
73
+ )
74
+ self.assertIs(hooks.subscribes("tool.before"), False)
75
+ self.assertIs(hooks.subscribes("tool.after"), True)
76
+ self.assertIs(hooks.subscribes("unknown.event"), False)
77
+
78
+
79
+ def model_capabilities():
80
+ return capability.HostCapabilities(
81
+ tool_before=capabilities().tool_before,
82
+ model_request_before=capability.ModelRequestBeforeCapabilities(observe=True),
83
+ model_response_after=capability.ModelResponseAfterCapabilities(
84
+ intercept=capability.ModelResponseAfterIntercept(message=True),
85
+ observe=True,
86
+ ),
87
+ )
88
+
89
+
90
+ def subscription(events, mode):
91
+ result = {"events": events, "mode": mode, "content": {"default": "metadata"}}
92
+ if mode == "intercept":
93
+ result.update(timeoutMs=1000, failurePolicy="fail-open")
94
+ return result
95
+
96
+
97
+ def hooks_for(subscriptions, declarations):
98
+ registration = config()
99
+ registration["hooks"][0]["subscriptions"] = subscriptions
100
+ return Hooks(
101
+ registration,
102
+ source="urn:test",
103
+ harness=protocol_event.Harness(name="test-host", version="1"),
104
+ capabilities=declarations,
105
+ )
106
+
107
+
108
+ class InterceptInterestTests(unittest.TestCase):
109
+ def test_intercept_only(self):
110
+ for selector in ("tool.before", "tool.*", "*"):
111
+ with self.subTest(selector=selector):
112
+ hooks = hooks_for(
113
+ [subscription([selector], "intercept")], capabilities()
114
+ )
115
+ before = deepcopy((hooks.config, hooks.capabilities))
116
+ with (
117
+ patch.object(
118
+ hooks, "_ensure_ready", side_effect=AssertionError("transport")
119
+ ),
120
+ patch.object(
121
+ hooks,
122
+ "_project_delivery",
123
+ side_effect=AssertionError("input preparation"),
124
+ ),
125
+ patch.object(
126
+ hooks.validator,
127
+ "validate",
128
+ side_effect=AssertionError("input validation"),
129
+ ),
130
+ ):
131
+ for _ in range(2):
132
+ self.assertIs(hooks.intercepts("tool.before"), True)
133
+ self.assertIs(hooks.intercepts("tool.after"), False)
134
+ self.assertIs(hooks.intercepts("unknown.event"), False)
135
+ self.assertIs(hooks.intercepts(""), False)
136
+ self.assertEqual((hooks.config, hooks.capabilities), before)
137
+
138
+ def test_observe_only(self):
139
+ for selector in ("tool.before", "tool.*", "*"):
140
+ with self.subTest(selector=selector):
141
+ hooks = hooks_for([subscription([selector], "observe")], capabilities())
142
+ self.assertIs(hooks.subscribes("tool.before"), True)
143
+ self.assertIs(hooks.intercepts("tool.before"), False)
144
+
145
+ def test_intercept_and_observe(self):
146
+ hooks = hooks_for(
147
+ [
148
+ subscription(["model.*"], "observe"),
149
+ subscription(["model.response.after"], "intercept"),
150
+ ],
151
+ model_capabilities(),
152
+ )
153
+ self.assertIs(hooks.intercepts("model.response.after"), True)
154
+ self.assertIs(hooks.subscribes("model.request.before"), True)
155
+ self.assertIs(hooks.intercepts("model.request.before"), False)
156
+ self.assertIs(hooks.intercepts("tool.before"), False)
157
+
158
+ def test_prefix_selector(self):
159
+ declarations = capability.HostCapabilities(
160
+ model_response_after=model_capabilities().model_response_after
161
+ )
162
+ hooks = hooks_for([subscription(["model.*"], "intercept")], declarations)
163
+ self.assertIs(hooks.intercepts("model.response.after"), True)
164
+ self.assertIs(hooks.intercepts("model.request.before"), False)
165
+ self.assertIs(hooks.intercepts("tool.before"), False)
166
+
167
+ def test_event_without_intercept_grant(self):
168
+ hooks = hooks_for(
169
+ [
170
+ subscription(["tool.before"], "intercept"),
171
+ subscription(["model.request.before"], "observe"),
172
+ ],
173
+ model_capabilities(),
174
+ )
175
+ self.assertIs(hooks.intercepts("tool.before"), True)
176
+ self.assertIs(hooks.subscribes("model.request.before"), True)
177
+ self.assertIs(hooks.intercepts("model.request.before"), False)
@@ -1,76 +0,0 @@
1
- """External public consumer coverage for synchronous static interest."""
2
-
3
- from agenthooksprotocol import event as protocol_event
4
- from agenthooksprotocol import capability
5
-
6
- from copy import deepcopy
7
- import unittest
8
- from unittest.mock import patch
9
-
10
- from agenthooksprotocol import Hooks
11
- from test_public_hooks import capabilities, config
12
-
13
-
14
- class SubscriptionInterestTests(unittest.TestCase):
15
- def test_static_interest(self):
16
- for mode in ("intercept", "observe"):
17
- for selector in ("tool.before", "tool.*", "*"):
18
- for filtered in (False, True):
19
- with self.subTest(mode=mode, selector=selector, filtered=filtered):
20
- registration = config(mode=mode)
21
- subscription = registration["hooks"][0]["subscriptions"][0]
22
- subscription["events"] = [selector]
23
- if filtered:
24
- subscription["filters"] = {
25
- "toolKinds": ["shell"],
26
- "paths": ["not-the-path"],
27
- }
28
- hooks = Hooks(
29
- registration,
30
- source="urn:test",
31
- harness=protocol_event.Harness(
32
- name="test-host", version="1"
33
- ),
34
- capabilities=capabilities(),
35
- )
36
- before = deepcopy((hooks.config, hooks.capabilities))
37
- with (
38
- patch.object(
39
- hooks,
40
- "_ensure_ready",
41
- side_effect=AssertionError("transport"),
42
- ),
43
- patch.object(
44
- hooks,
45
- "_project_delivery",
46
- side_effect=AssertionError("input preparation"),
47
- ),
48
- patch.object(
49
- hooks.validator,
50
- "validate",
51
- side_effect=AssertionError("input validation"),
52
- ),
53
- ):
54
- for _ in range(2):
55
- self.assertIs(hooks.subscribes("tool.before"), True)
56
- self.assertIs(hooks.subscribes("tool.after"), False)
57
- self.assertIs(hooks.subscribes("unknown.event"), False)
58
- self.assertIs(hooks.subscribes(""), False)
59
- self.assertEqual((hooks.config, hooks.capabilities), before)
60
-
61
- def test_no_subscribers_and_unrelated_selectors(self):
62
- declarations = capability.HostCapabilities(
63
- tool_before=capabilities().tool_before,
64
- tool_after=capability.ToolAfterCapabilities(observe=True),
65
- )
66
- registration = config(mode="observe")
67
- registration["hooks"][0]["subscriptions"][0]["events"] = ["tool.after"]
68
- hooks = Hooks(
69
- registration,
70
- source="urn:test",
71
- harness=protocol_event.Harness(name="test-host", version="1"),
72
- capabilities=declarations,
73
- )
74
- self.assertIs(hooks.subscribes("tool.before"), False)
75
- self.assertIs(hooks.subscribes("tool.after"), True)
76
- self.assertIs(hooks.subscribes("unknown.event"), False)