agenthooksprotocol 0.4.1__tar.gz → 0.6.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.4.1/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.6.0}/PKG-INFO +49 -26
  2. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/README.md +48 -25
  3. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/pyproject.toml +1 -1
  4. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/__init__.py +3 -3
  5. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_content.py +0 -13
  6. agenthooksprotocol-0.6.0/src/agenthooksprotocol/_grants.py +1965 -0
  7. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_hooks.py +145 -186
  8. agenthooksprotocol-0.6.0/src/agenthooksprotocol/_host_metadata.py +133 -0
  9. agenthooksprotocol-0.4.1/src/agenthooksprotocol/content.py → agenthooksprotocol-0.6.0/src/agenthooksprotocol/_interop_content.py +4 -30
  10. agenthooksprotocol-0.6.0/src/agenthooksprotocol/_interop_hooks.py +48 -0
  11. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/__init__.py +398 -1758
  12. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/content.py +0 -10
  13. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/event.py +2 -0
  14. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/tool.py +0 -2
  15. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_outcomes.py +9 -8
  16. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/ahp-codegen.lock.json +3 -3
  17. agenthooksprotocol-0.6.0/src/agenthooksprotocol/capability.py +76 -0
  18. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/catalogue.py +43 -6
  19. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/codec.py +2 -2
  20. agenthooksprotocol-0.6.0/src/agenthooksprotocol/content.py +28 -0
  21. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/diagnostics.py +0 -3
  22. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/effect.py +0 -275
  23. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/event.py +1 -0
  24. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/generated.py +2 -1
  25. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/integrations/pydantic.py +3 -3
  26. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/interop.py +24 -26
  27. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle_client.py +1 -1
  28. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle_server.py +17 -27
  29. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/observation_chain.py +3 -3
  30. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/response.py +2 -2
  31. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/runtime.py +20 -10
  32. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/schemas.json +7 -0
  33. agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/__init__.py +10 -0
  34. agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/_admission.py +43 -0
  35. agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/_handlers.py +1063 -0
  36. agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/_slots.py +45 -0
  37. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/asgi.py +2 -6
  38. agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/hooks.py +268 -0
  39. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/stdio.py +4 -4
  40. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/tool.py +0 -1
  41. agenthooksprotocol-0.6.0/src/agenthooksprotocol/transports/stdio.py +297 -0
  42. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0/src/agenthooksprotocol.egg-info}/PKG-INFO +49 -26
  43. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/SOURCES.txt +15 -0
  44. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_attachments.py +55 -25
  45. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_compaction.py +11 -3
  46. agenthooksprotocol-0.6.0/tests/test_consumer_outcomes.py +398 -0
  47. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_content.py +1 -1
  48. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_content_lifetime.py +4 -2
  49. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_content_receipts.py +5 -2
  50. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_correlated_core.py +52 -13
  51. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_declared_contracts.py +226 -70
  52. agenthooksprotocol-0.6.0/tests/test_event_types.py +40 -0
  53. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_fixture_public.py +2 -2
  54. agenthooksprotocol-0.6.0/tests/test_handwritten_surface.py +125 -0
  55. agenthooksprotocol-0.6.0/tests/test_host_metadata.py +130 -0
  56. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_inline_messages.py +72 -34
  57. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_lifecycle_auth.py +1 -1
  58. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_owned_content_hooks.py +18 -4
  59. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_content.py +174 -64
  60. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_contract_surface.py +9 -3
  61. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_examples.py +20 -1
  62. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_hooks.py +61 -39
  63. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_server.py +273 -30
  64. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_sdk_unification.py +96 -36
  65. agenthooksprotocol-0.6.0/tests/test_server_catch_all.py +101 -0
  66. agenthooksprotocol-0.6.0/tests/test_server_error_codes.py +171 -0
  67. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_session_manifest.py +66 -28
  68. agenthooksprotocol-0.6.0/tests/test_stdio_env.py +153 -0
  69. agenthooksprotocol-0.6.0/tests/test_stdio_transport.py +132 -0
  70. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_structural_facade.py +148 -39
  71. agenthooksprotocol-0.6.0/tests/test_subscribes.py +65 -0
  72. agenthooksprotocol-0.6.0/tests/test_typed_capabilities.py +173 -0
  73. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_typed_contract_regressions.py +141 -39
  74. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_upload_planning.py +35 -9
  75. agenthooksprotocol-0.4.1/src/agenthooksprotocol/_grants.py +0 -619
  76. agenthooksprotocol-0.4.1/src/agenthooksprotocol/capability.py +0 -155
  77. agenthooksprotocol-0.4.1/src/agenthooksprotocol/server/__init__.py +0 -8
  78. agenthooksprotocol-0.4.1/src/agenthooksprotocol/server/hooks.py +0 -166
  79. agenthooksprotocol-0.4.1/src/agenthooksprotocol/transports/stdio.py +0 -92
  80. agenthooksprotocol-0.4.1/tests/test_consumer_outcomes.py +0 -146
  81. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/LICENSE +0 -0
  82. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/setup.cfg +0 -0
  83. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_boundaries.py +0 -0
  84. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_diagnostics.py +0 -0
  85. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_elicitation.py +0 -0
  86. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/capability.py +0 -0
  87. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/effect.py +0 -0
  88. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/registration.py +0 -0
  89. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/subscription.py +0 -0
  90. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/transport.py +0 -0
  91. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/attachment.py +0 -0
  92. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/auth.py +0 -0
  93. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/candidate.py +0 -0
  94. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/compaction.py +0 -0
  95. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/contract.py +0 -0
  96. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/elicitation.py +0 -0
  97. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/integrations/__init__.py +0 -0
  98. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle.py +0 -0
  99. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lineage.py +0 -0
  100. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/path.py +0 -0
  101. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/permission.py +0 -0
  102. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/py.typed +0 -0
  103. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/registration.py +0 -0
  104. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_framing.py +0 -0
  105. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_json.py +0 -0
  106. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/attachments.py +0 -0
  107. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/state.py +0 -0
  108. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/subscription.py +0 -0
  109. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transport.py +0 -0
  110. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transports/__init__.py +0 -0
  111. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transports/http.py +0 -0
  112. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/wire.py +0 -0
  113. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/dependency_links.txt +0 -0
  114. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/requires.txt +0 -0
  115. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/top_level.txt +0 -0
  116. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_catalogue.py +0 -0
  117. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_codec.py +0 -0
  118. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_compaction_wire.py +0 -0
  119. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_elicitation_adapter.py +0 -0
  120. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_integration.py +0 -0
  121. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_integration_edges.py +0 -0
  122. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_interop.py +0 -0
  123. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_lifecycle.py +0 -0
  124. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_observation.py +0 -0
  125. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_observation_chain_transport.py +0 -0
  126. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_owned_content.py +0 -0
  127. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_package.py +0 -0
  128. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_registration_auth.py +0 -0
  129. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_safety.py +0 -0
  130. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_schema_corrections.py +0 -0
  131. {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_shared_materialization.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agenthooksprotocol
3
- Version: 0.4.1
3
+ Version: 0.6.0
4
4
  Summary: Official non-normative Python SDK for the Agent Hooks Protocol
5
5
  Author: Agent Hooks Protocol maintainers
6
6
  License:
@@ -250,9 +250,13 @@ with open("hooks.json") as file:
250
250
  config = json.load(file)
251
251
 
252
252
  async def review(existing_arguments):
253
- async with Hooks(config, source="urn:example:harness", capabilities={
254
- capability.Event.TOOL_BEFORE: capability.intercept().allow().deny().modify_input(replace=True),
255
- }) as hooks:
253
+ async with Hooks(config, source="urn:example:harness", capabilities=capability.HostCapabilities(
254
+ tool_before=capability.ToolBeforeCapabilities(
255
+ intercept=capability.ToolBeforeIntercept(
256
+ allow=True, deny=True, modify_input=capability.Modify.REPLACE,
257
+ ),
258
+ ),
259
+ )) as hooks:
256
260
  result = await hooks.tool_before(event.ToolBeforeInput(
257
261
  call_id="call-1", name="read_file", input=existing_arguments,
258
262
  path="native", origin="native",
@@ -260,16 +264,32 @@ async def review(existing_arguments):
260
264
  return result # Host validation and authorization still precede execution.
261
265
  ```
262
266
 
263
- 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 and the configured session manifest. Low-level `dispatch` accepts canonical dictionaries.
267
+ 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 and the configured session manifest. 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.
264
268
 
265
- Capability builders are immutable: reusing a base declaration does not widen it. `intercept()` deliberately advertises **both intercept and observe**; `observe()` is observation-only. `modify_input(replace=True)` supplies both the effect grant and operation block. Empty operations and observation effect grants are rejected; boundary compatibility is validated before delivery. Form and URL elicitation grants are explicit (`elicitation_form()` / `elicitation_url()`). Raw manifests retain their exact modes; omission never implies permission. Per-call `capabilities=` only narrows configured grants.
269
+ 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.
270
+
271
+ ```python
272
+ from agenthooksprotocol import capability
273
+
274
+ capabilities = capability.HostCapabilities(
275
+ tool_before=capability.ToolBeforeCapabilities(
276
+ intercept=capability.ToolBeforeIntercept(
277
+ allow=True, deny=True, modify_input=capability.Modify.REPLACE
278
+ ),
279
+ observe=True, # intercept and observe
280
+ ),
281
+ session_end=capability.SessionEndCapabilities(observe=True), # observe only
282
+ )
283
+ assert capabilities.to_wire()["tool.before"]["modes"] == ["intercept", "observe"]
284
+ assert capabilities.to_wire()["session.end"] == {"modes": ["observe"]}
285
+ ```
266
286
 
267
287
  Runnable, statically checked consumer programs live in [`examples/`](examples):
268
288
 
269
289
  - `value_codecs.py`: independent argument/result/provenance codecs, admission-time invariants, and a form schema derived from its answer type.
270
290
  - `typed_tool.py`: JSON registration, generated tool input, typed grants, initial state, real in-process ASGI handler, borrowed HTTP client, and explicit application decoding.
271
291
  - `common_cases.py`: rewrite/allow, deny, invalid application shape, host policy, occurrence narrowing, native initial state, and fail-open/fail-closed reports. The host operation is an in-memory execution recorder, not a shell.
272
- - `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public Handler, denial, and child cleanup.
292
+ - `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public `hooks.Handlers`, denial, and child cleanup.
273
293
  - `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified upload receipt, and caller-owned immutable storage.
274
294
 
275
295
  - `lifecycle.py`: caller-owned task groups, operation-owned observations, interrupted requests, idempotent close, and proof that an owned subprocess was reaped.
@@ -285,17 +305,17 @@ Capabilities explicitly grant effects and target operations. Supply event capabi
285
305
 
286
306
  Supply `input_codec=`, `result_codec=`, and optional `provenance_codec=` to a named hook method or `dispatch` to declare caller types. Complete staged values are decoded and validated before publication. Object merge is shallow: omitted fields remain unchanged, literal null is retained, and nested values replace whole values. An invalid response publishes none of its effects; earlier accepted responses remain visible to later interceptors. A codec must preserve the wire data it receives, including opaque extra fields. Lossy serialization rejects admission rather than dropping fields.
287
307
 
288
- `result.decoded_input` exposes the declared argument value. `result.decoded_candidate` is an application `Candidate[Result, Provenance]`, or `None` when there is no candidate. Its value can itself be `None`; optional provenance is omitted from `candidate.to_dict()` when absent. Raw `input` and `candidate` views remain detached snapshots. For explicitly selected opaque host slots, use `event_codecs={("params",): codec}` with event-relative paths. Unspecified native, provider, task, permission, and discovery values are not interpreted.
308
+ `result.input` exposes the declared argument value. `result.candidate` is an SDK-owned `Candidate[Result, Provenance]`, or `None` when there is no candidate. Its value can itself be `None`; optional provenance is omitted from `candidate.to_dict()` when absent. Both values are detached snapshots. Without caller codecs, protocol-owned candidate values use canonical typed models and application-owned values remain JSON. `result.event` is the canonical typed event; `result.accepted_responses` retains complete contextual response envelopes in settlement order. `result.messages` and `result.injections` contain typed effects, including injection delivery timing. `result.has_result` distinguishes absence from a supplied null deliverable; `result.result` raises `KeyError` when absent. `result.flow` is the settled `state.Flow`, or `None` when no flow state is supplied; explicit neutral flow is `state.Flow.NONE`. `result.instructions` includes inherited and accepted continuation instructions, with `None` when absent and `[]` for an effective empty list. `result.continuation_remaining` is the settled budget, or `None` when no budget is declared. For explicitly selected opaque host slots, use `event_codecs={("params",): codec}` with event-relative paths. Unspecified native, provider, task, permission, and discovery values are not interpreted.
289
309
 
290
310
  For forms, construct `PydanticFormContract(TypeAdapter(Answer))` from one answer declaration. `request(message)` derives the restricted MCP schema; `result_codec()` decodes the complete MCP result and its accepted answer while preserving opaque result metadata. Unsupported shapes and schema constraints are rejected during construction. Decline, cancel, and URL results have no form content. See [`examples/value_codecs.py`](examples/value_codecs.py).
291
311
 
292
- After settlement, explicitly decode effective input with `result.decode_input(codec)`. A codec implements `encode(value)` and `decode(json_value)`; `IdentityCodec` copies JSON. The optional `integrations.pydantic.PydanticCodec` accepts a Pydantic `TypeAdapter`. A decoding error does not retroactively reject protocol effects: retain the settled result, raw effective input, accepted responses, and diagnostics, and report host-level rejection without executing.
312
+ A codec implements `encode(value)` and `decode(json_value)`; `IdentityCodec` copies JSON. The optional `integrations.pydantic.PydanticCodec` accepts a Pydantic `TypeAdapter`. Hosts can call `codec.decode(result.input)` for an explicit application check when no input codec is declared. A post-settlement application error does not retroactively reject protocol effects: retain the settled result, accepted responses, and diagnostics, and report host-level rejection without executing.
293
313
 
294
- `result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is detached accepted JSON. Declared codecs validate accepted modifications; without a declared codec, the host supplies application validation. `decode_input(codec)` remains an explicit, post-settlement host check. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
314
+ `result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is the detached accepted argument value. Declared codecs validate accepted modifications; without a declared codec, the host supplies application validation. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
295
315
 
296
316
  `state.initial(Permission.ALLOW)` represents a native decision **already made for this exact occurrence**, not an authorization shortcut. Its default candidate is absent (`null`); `state.Candidate(value=None)` instead means a supplied JSON-null result. Optional typed provenance records facts, not authenticated identity or execution proof. Canonical modifications still invalidate candidates/approval as specified.
297
317
 
298
- Generated backend helpers such as `effect.deny(reason="policy")`, `effect.replace_input(new_args)` and `effect.merge_input(changes)`, and `effect.Return(value=...)` fill discriminants and return canonical effect models. They cannot grant themselves authority: unsupported compound responses are rejected atomically.
318
+ Generated backend helpers such as `effect.DenyEffect(reason="policy")`, `effect.replace_input(new_args)` and `effect.merge_input(changes)`, and `effect.ReturnToolEffect(value=...)` fill discriminants and return canonical effect models. They cannot grant themselves authority: unsupported compound responses are rejected atomically.
299
319
 
300
320
  ### Diagnostics and one call budget
301
321
 
@@ -318,17 +338,23 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
318
338
 
319
339
  The default `auth.EnvironmentAuthProvider` resolves bearer `tokenEnv` or optional `resolve_credential` tokenRef callbacks at delivery time. OAuth bindings require an explicit provider. Missing configured secrets and unsupported mechanisms fail closed. Anonymous success stays anonymous; an explicit provider can authorize challenge discovery under host trust policy. Interception may replay at most once after an eligible 401 Bearer challenge, retaining request identity and serialized body; observations/uploads are never automatically replayed. Upload bindings are independent: event credentials are never an upload fallback. Transport-owned TLS/workload integration is not replaced by this provider.
320
340
 
341
+ Registered stdio backends start with a minimal base environment rather than the full host environment. The base is an allowlist of host variables: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TZ`, `TMPDIR`, `TEMP` and `TMP`, plus `SYSTEMROOT`, `WINDIR`, `COMSPEC`, `PATHEXT`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA` and `PROGRAMDATA` on Windows, where names match case-insensitively. The registration's `transport.env` entries are applied on top as literal strings, with no interpolation, and override base values. `tokenEnv` is still resolved in the host environment and credentials are never copied into the child. Env values are never logged. `Hooks(..., inherit_environment=True)` is an SDK-level opt-out that starts from the full host environment instead. `transports.StdioTransport(..., env=..., inherit_environment=...)` exposes the same controls.
342
+
321
343
  ## Static host manifest
322
344
 
323
- Configure `Hooks(config, *, source, manifest=full_manifest, transport=None, auth_provider=None)` with a complete canonical static manifest, **or** use `capabilities=event_declarations`. These options are mutually exclusive. The full manifest supplies the same event/mode/effect authority used for admission; it is not backend discovery. `hooks.manifest` returns a detached snapshot.
345
+ `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.
346
+
347
+ Configure `Hooks(config, *, source, capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. 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.
324
348
 
325
- The event-map shorthand advertises only explicitly declared events and modes. Its derived manifest records a gap for every omitted canonical event and for host-level facilities that the map cannot establish (transports, authentication, tool paths, content categories, limits, and managed policy). Empty lists do not mean universal support. Use a full manifest to declare those facilities accurately; explicit full manifests are preserved rather than augmented with assumed support.
349
+ 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.
326
350
 
327
351
  `await hooks.session_start(event.SessionStartInput(session=..., trigger="startup", harness=..., permission_mode="default", items=[]))` needs only occurrence-specific host facts. The SDK supplies `manifest`, `type`, and `source`, and supplies `id`/`time` when absent; `event_id=` takes precedence over a supplied ID. Caller payload fields cannot override the configured type, source, or manifest. Configuration, manifest snapshots, and delivered occurrences are independent copies. See [`examples/session_manifest.py`](examples/session_manifest.py) for a runnable, typechecked receiver example.
328
352
 
329
353
  ## Backend servers
330
354
 
331
- `from agenthooksprotocol.server import hooks` exposes the small `hooks.Handler(intercept=..., observe=...)` callback surface and `hooks.InterceptResult`. Both callbacks are asynchronous and receive canonical generated protocol requests. The same protocol dispatcher serves stdio and the framework-neutral ASGI adapter. ASGI does not require Starlette or FastAPI.
355
+ `from agenthooksprotocol.server import hooks` exposes event-correlated callback maps. Configure `hooks.Handlers(intercept=hooks.InterceptHandlers(tool_before=before), observe=hooks.ObserveHandlers(tool_before=observer))`. A tool interception callback accepts `hooks.ToolBeforeContext` and returns `hooks.ToolBeforeReply`; an observation callback accepts `hooks.ToolBeforeObserveContext` and returns `None`. Callbacks can be synchronous or asynchronous. Contexts expose the typed event, full params/envelope, and detached raw evidence; interception contexts also expose request-time capabilities and state. Reply envelopes and correlation IDs belong to the server. `hooks.ObserveHandlers(any=observer)` adds an optional catch-all that receives a `hooks.AnyObserveContext` for observed events without their own observer field. `from agenthooksprotocol.server import serve` is the AnyIO stdio server (`server.stdio.serve`).
356
+
357
+ `hooks.ToolBeforeReply(effects=(hooks.ReplaceInput(arguments), effect.Allow()))` preserves effect order. `hooks.ToolBeforeReply()` is a valid no-op. Reply types constrain event-specific controls; runtime validation still checks canonical/contextual legality and dynamic request grants. Tool contexts provide `decode_input(codec)` and `decode_candidate(result_codec, provenance_codec)` for caller-owned application types without discarding original wire evidence. The same dispatcher serves stdio and the framework-neutral ASGI adapter; ASGI does not require Starlette or FastAPI.
332
358
 
333
359
  Observation is one-way. It does not acquire effect authority and never waits for an acknowledgement. An optional static **harness** manifest can expose `hooks/capabilities`; backend callbacks are not capability discovery and do not manufacture grants.
334
360
 
@@ -434,8 +460,9 @@ or `sha256`. Metadata-only content and body gaps may still disclose size/digest.
434
460
 
435
461
  ```python
436
462
  from agenthooksprotocol import ContentReference, capability, effect
463
+ from agenthooksprotocol._models.capability import Capabilities
437
464
 
438
- caps = capability.Capabilities.from_dict({"effects": ["deny", "vendor.custom"]})
465
+ caps = Capabilities.from_dict({"effects": ["deny", "vendor.custom"]})
439
466
  assert caps.supports(capability.EffectName.DENY)
440
467
  assert caps.supports("vendor.custom")
441
468
  assert effect.EffectName is capability.EffectName
@@ -465,21 +492,17 @@ non-finite numbers and non-JSON values are rejected. Parsing raw JSON through
465
492
 
466
493
  Provide valid enum/literal values and all required wire members to `from_dict`. A null candidate, a candidate with
467
494
  `{"value": null}`, and a candidate with `{"value": 0}` remain distinct; omitting a
468
- required candidate is an error. Generated input projections and capability grant
469
- builders are construction helpers, not wire decode entrypoints; their final wire
470
- objects are validated at the dispatch/parse boundary. Direct dictionary
495
+ required candidate is an error. Generated input projections and frozen host capability
496
+ models are construction APIs, not wire decode entrypoints; their canonical wire
497
+ values are validated at the dispatch/parse boundary. Direct dictionary
471
498
  mutation, standard-library `json.loads`, TypedDict annotations, and type assertions
472
499
  are not SDK validation entrypoints. Re-parse after manually mutating a mapping.
473
500
 
474
- Nested model attributes expose declared protocol fields. For example, `capability.Capabilities(effects=["modify"], modify={}).modify.input` is `None` when that grant is absent. Family queries are available on generic and per-occurrence capability models.
501
+ Nested model attributes expose declared protocol fields. For example, `Capabilities(effects=["modify"], modify={}).modify.input` is `None` when that grant is absent. Family queries are available on generic and per-occurrence capability models.
475
502
 
476
- Constructor aliases cannot silently overwrite wire keys. Supplying both
477
- `tool_name=` and `toolName=` raises `TypeError`, even if the values agree. For
478
- optional/defaulted fields, a lone wire spelling (for example `addressForm=` or
479
- `protocolVersion=`) is used and validated rather than replaced by a default.
480
- Required constructor parameters use their documented Python spelling;
481
- use `from_dict` to decode complete wire-keyed objects. In `from_dict`, distinct
482
- keys such as `toolName` and `tool_name` remain distinct wire/extension keys.
503
+ Use the documented Python spelling for constructor parameters. Use `from_dict`
504
+ to decode complete wire-keyed objects. In `from_dict`, distinct keys such as
505
+ `toolName` and `tool_name` remain distinct wire/extension keys.
483
506
 
484
507
  ### Owned attachments
485
508
 
@@ -26,9 +26,13 @@ with open("hooks.json") as file:
26
26
  config = json.load(file)
27
27
 
28
28
  async def review(existing_arguments):
29
- async with Hooks(config, source="urn:example:harness", capabilities={
30
- capability.Event.TOOL_BEFORE: capability.intercept().allow().deny().modify_input(replace=True),
31
- }) as hooks:
29
+ async with Hooks(config, source="urn:example:harness", capabilities=capability.HostCapabilities(
30
+ tool_before=capability.ToolBeforeCapabilities(
31
+ intercept=capability.ToolBeforeIntercept(
32
+ allow=True, deny=True, modify_input=capability.Modify.REPLACE,
33
+ ),
34
+ ),
35
+ )) as hooks:
32
36
  result = await hooks.tool_before(event.ToolBeforeInput(
33
37
  call_id="call-1", name="read_file", input=existing_arguments,
34
38
  path="native", origin="native",
@@ -36,16 +40,32 @@ async def review(existing_arguments):
36
40
  return result # Host validation and authorization still precede execution.
37
41
  ```
38
42
 
39
- 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 and the configured session manifest. Low-level `dispatch` accepts canonical dictionaries.
43
+ 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 and the configured session manifest. 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.
40
44
 
41
- Capability builders are immutable: reusing a base declaration does not widen it. `intercept()` deliberately advertises **both intercept and observe**; `observe()` is observation-only. `modify_input(replace=True)` supplies both the effect grant and operation block. Empty operations and observation effect grants are rejected; boundary compatibility is validated before delivery. Form and URL elicitation grants are explicit (`elicitation_form()` / `elicitation_url()`). Raw manifests retain their exact modes; omission never implies permission. Per-call `capabilities=` only narrows configured grants.
45
+ 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.
46
+
47
+ ```python
48
+ from agenthooksprotocol import capability
49
+
50
+ capabilities = capability.HostCapabilities(
51
+ tool_before=capability.ToolBeforeCapabilities(
52
+ intercept=capability.ToolBeforeIntercept(
53
+ allow=True, deny=True, modify_input=capability.Modify.REPLACE
54
+ ),
55
+ observe=True, # intercept and observe
56
+ ),
57
+ session_end=capability.SessionEndCapabilities(observe=True), # observe only
58
+ )
59
+ assert capabilities.to_wire()["tool.before"]["modes"] == ["intercept", "observe"]
60
+ assert capabilities.to_wire()["session.end"] == {"modes": ["observe"]}
61
+ ```
42
62
 
43
63
  Runnable, statically checked consumer programs live in [`examples/`](examples):
44
64
 
45
65
  - `value_codecs.py`: independent argument/result/provenance codecs, admission-time invariants, and a form schema derived from its answer type.
46
66
  - `typed_tool.py`: JSON registration, generated tool input, typed grants, initial state, real in-process ASGI handler, borrowed HTTP client, and explicit application decoding.
47
67
  - `common_cases.py`: rewrite/allow, deny, invalid application shape, host policy, occurrence narrowing, native initial state, and fail-open/fail-closed reports. The host operation is an in-memory execution recorder, not a shell.
48
- - `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public Handler, denial, and child cleanup.
68
+ - `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public `hooks.Handlers`, denial, and child cleanup.
49
69
  - `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified upload receipt, and caller-owned immutable storage.
50
70
 
51
71
  - `lifecycle.py`: caller-owned task groups, operation-owned observations, interrupted requests, idempotent close, and proof that an owned subprocess was reaped.
@@ -61,17 +81,17 @@ Capabilities explicitly grant effects and target operations. Supply event capabi
61
81
 
62
82
  Supply `input_codec=`, `result_codec=`, and optional `provenance_codec=` to a named hook method or `dispatch` to declare caller types. Complete staged values are decoded and validated before publication. Object merge is shallow: omitted fields remain unchanged, literal null is retained, and nested values replace whole values. An invalid response publishes none of its effects; earlier accepted responses remain visible to later interceptors. A codec must preserve the wire data it receives, including opaque extra fields. Lossy serialization rejects admission rather than dropping fields.
63
83
 
64
- `result.decoded_input` exposes the declared argument value. `result.decoded_candidate` is an application `Candidate[Result, Provenance]`, or `None` when there is no candidate. Its value can itself be `None`; optional provenance is omitted from `candidate.to_dict()` when absent. Raw `input` and `candidate` views remain detached snapshots. For explicitly selected opaque host slots, use `event_codecs={("params",): codec}` with event-relative paths. Unspecified native, provider, task, permission, and discovery values are not interpreted.
84
+ `result.input` exposes the declared argument value. `result.candidate` is an SDK-owned `Candidate[Result, Provenance]`, or `None` when there is no candidate. Its value can itself be `None`; optional provenance is omitted from `candidate.to_dict()` when absent. Both values are detached snapshots. Without caller codecs, protocol-owned candidate values use canonical typed models and application-owned values remain JSON. `result.event` is the canonical typed event; `result.accepted_responses` retains complete contextual response envelopes in settlement order. `result.messages` and `result.injections` contain typed effects, including injection delivery timing. `result.has_result` distinguishes absence from a supplied null deliverable; `result.result` raises `KeyError` when absent. `result.flow` is the settled `state.Flow`, or `None` when no flow state is supplied; explicit neutral flow is `state.Flow.NONE`. `result.instructions` includes inherited and accepted continuation instructions, with `None` when absent and `[]` for an effective empty list. `result.continuation_remaining` is the settled budget, or `None` when no budget is declared. For explicitly selected opaque host slots, use `event_codecs={("params",): codec}` with event-relative paths. Unspecified native, provider, task, permission, and discovery values are not interpreted.
65
85
 
66
86
  For forms, construct `PydanticFormContract(TypeAdapter(Answer))` from one answer declaration. `request(message)` derives the restricted MCP schema; `result_codec()` decodes the complete MCP result and its accepted answer while preserving opaque result metadata. Unsupported shapes and schema constraints are rejected during construction. Decline, cancel, and URL results have no form content. See [`examples/value_codecs.py`](examples/value_codecs.py).
67
87
 
68
- After settlement, explicitly decode effective input with `result.decode_input(codec)`. A codec implements `encode(value)` and `decode(json_value)`; `IdentityCodec` copies JSON. The optional `integrations.pydantic.PydanticCodec` accepts a Pydantic `TypeAdapter`. A decoding error does not retroactively reject protocol effects: retain the settled result, raw effective input, accepted responses, and diagnostics, and report host-level rejection without executing.
88
+ A codec implements `encode(value)` and `decode(json_value)`; `IdentityCodec` copies JSON. The optional `integrations.pydantic.PydanticCodec` accepts a Pydantic `TypeAdapter`. Hosts can call `codec.decode(result.input)` for an explicit application check when no input codec is declared. A post-settlement application error does not retroactively reject protocol effects: retain the settled result, accepted responses, and diagnostics, and report host-level rejection without executing.
69
89
 
70
- `result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is detached accepted JSON. Declared codecs validate accepted modifications; without a declared codec, the host supplies application validation. `decode_input(codec)` remains an explicit, post-settlement host check. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
90
+ `result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is the detached accepted argument value. Declared codecs validate accepted modifications; without a declared codec, the host supplies application validation. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
71
91
 
72
92
  `state.initial(Permission.ALLOW)` represents a native decision **already made for this exact occurrence**, not an authorization shortcut. Its default candidate is absent (`null`); `state.Candidate(value=None)` instead means a supplied JSON-null result. Optional typed provenance records facts, not authenticated identity or execution proof. Canonical modifications still invalidate candidates/approval as specified.
73
93
 
74
- Generated backend helpers such as `effect.deny(reason="policy")`, `effect.replace_input(new_args)` and `effect.merge_input(changes)`, and `effect.Return(value=...)` fill discriminants and return canonical effect models. They cannot grant themselves authority: unsupported compound responses are rejected atomically.
94
+ Generated backend helpers such as `effect.DenyEffect(reason="policy")`, `effect.replace_input(new_args)` and `effect.merge_input(changes)`, and `effect.ReturnToolEffect(value=...)` fill discriminants and return canonical effect models. They cannot grant themselves authority: unsupported compound responses are rejected atomically.
75
95
 
76
96
  ### Diagnostics and one call budget
77
97
 
@@ -94,17 +114,23 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
94
114
 
95
115
  The default `auth.EnvironmentAuthProvider` resolves bearer `tokenEnv` or optional `resolve_credential` tokenRef callbacks at delivery time. OAuth bindings require an explicit provider. Missing configured secrets and unsupported mechanisms fail closed. Anonymous success stays anonymous; an explicit provider can authorize challenge discovery under host trust policy. Interception may replay at most once after an eligible 401 Bearer challenge, retaining request identity and serialized body; observations/uploads are never automatically replayed. Upload bindings are independent: event credentials are never an upload fallback. Transport-owned TLS/workload integration is not replaced by this provider.
96
116
 
117
+ Registered stdio backends start with a minimal base environment rather than the full host environment. The base is an allowlist of host variables: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TZ`, `TMPDIR`, `TEMP` and `TMP`, plus `SYSTEMROOT`, `WINDIR`, `COMSPEC`, `PATHEXT`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA` and `PROGRAMDATA` on Windows, where names match case-insensitively. The registration's `transport.env` entries are applied on top as literal strings, with no interpolation, and override base values. `tokenEnv` is still resolved in the host environment and credentials are never copied into the child. Env values are never logged. `Hooks(..., inherit_environment=True)` is an SDK-level opt-out that starts from the full host environment instead. `transports.StdioTransport(..., env=..., inherit_environment=...)` exposes the same controls.
118
+
97
119
  ## Static host manifest
98
120
 
99
- Configure `Hooks(config, *, source, manifest=full_manifest, transport=None, auth_provider=None)` with a complete canonical static manifest, **or** use `capabilities=event_declarations`. These options are mutually exclusive. The full manifest supplies the same event/mode/effect authority used for admission; it is not backend discovery. `hooks.manifest` returns a detached snapshot.
121
+ `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.
122
+
123
+ Configure `Hooks(config, *, source, capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. 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.
100
124
 
101
- The event-map shorthand advertises only explicitly declared events and modes. Its derived manifest records a gap for every omitted canonical event and for host-level facilities that the map cannot establish (transports, authentication, tool paths, content categories, limits, and managed policy). Empty lists do not mean universal support. Use a full manifest to declare those facilities accurately; explicit full manifests are preserved rather than augmented with assumed support.
125
+ 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.
102
126
 
103
127
  `await hooks.session_start(event.SessionStartInput(session=..., trigger="startup", harness=..., permission_mode="default", items=[]))` needs only occurrence-specific host facts. The SDK supplies `manifest`, `type`, and `source`, and supplies `id`/`time` when absent; `event_id=` takes precedence over a supplied ID. Caller payload fields cannot override the configured type, source, or manifest. Configuration, manifest snapshots, and delivered occurrences are independent copies. See [`examples/session_manifest.py`](examples/session_manifest.py) for a runnable, typechecked receiver example.
104
128
 
105
129
  ## Backend servers
106
130
 
107
- `from agenthooksprotocol.server import hooks` exposes the small `hooks.Handler(intercept=..., observe=...)` callback surface and `hooks.InterceptResult`. Both callbacks are asynchronous and receive canonical generated protocol requests. The same protocol dispatcher serves stdio and the framework-neutral ASGI adapter. ASGI does not require Starlette or FastAPI.
131
+ `from agenthooksprotocol.server import hooks` exposes event-correlated callback maps. Configure `hooks.Handlers(intercept=hooks.InterceptHandlers(tool_before=before), observe=hooks.ObserveHandlers(tool_before=observer))`. A tool interception callback accepts `hooks.ToolBeforeContext` and returns `hooks.ToolBeforeReply`; an observation callback accepts `hooks.ToolBeforeObserveContext` and returns `None`. Callbacks can be synchronous or asynchronous. Contexts expose the typed event, full params/envelope, and detached raw evidence; interception contexts also expose request-time capabilities and state. Reply envelopes and correlation IDs belong to the server. `hooks.ObserveHandlers(any=observer)` adds an optional catch-all that receives a `hooks.AnyObserveContext` for observed events without their own observer field. `from agenthooksprotocol.server import serve` is the AnyIO stdio server (`server.stdio.serve`).
132
+
133
+ `hooks.ToolBeforeReply(effects=(hooks.ReplaceInput(arguments), effect.Allow()))` preserves effect order. `hooks.ToolBeforeReply()` is a valid no-op. Reply types constrain event-specific controls; runtime validation still checks canonical/contextual legality and dynamic request grants. Tool contexts provide `decode_input(codec)` and `decode_candidate(result_codec, provenance_codec)` for caller-owned application types without discarding original wire evidence. The same dispatcher serves stdio and the framework-neutral ASGI adapter; ASGI does not require Starlette or FastAPI.
108
134
 
109
135
  Observation is one-way. It does not acquire effect authority and never waits for an acknowledgement. An optional static **harness** manifest can expose `hooks/capabilities`; backend callbacks are not capability discovery and do not manufacture grants.
110
136
 
@@ -210,8 +236,9 @@ or `sha256`. Metadata-only content and body gaps may still disclose size/digest.
210
236
 
211
237
  ```python
212
238
  from agenthooksprotocol import ContentReference, capability, effect
239
+ from agenthooksprotocol._models.capability import Capabilities
213
240
 
214
- caps = capability.Capabilities.from_dict({"effects": ["deny", "vendor.custom"]})
241
+ caps = Capabilities.from_dict({"effects": ["deny", "vendor.custom"]})
215
242
  assert caps.supports(capability.EffectName.DENY)
216
243
  assert caps.supports("vendor.custom")
217
244
  assert effect.EffectName is capability.EffectName
@@ -241,21 +268,17 @@ non-finite numbers and non-JSON values are rejected. Parsing raw JSON through
241
268
 
242
269
  Provide valid enum/literal values and all required wire members to `from_dict`. A null candidate, a candidate with
243
270
  `{"value": null}`, and a candidate with `{"value": 0}` remain distinct; omitting a
244
- required candidate is an error. Generated input projections and capability grant
245
- builders are construction helpers, not wire decode entrypoints; their final wire
246
- objects are validated at the dispatch/parse boundary. Direct dictionary
271
+ required candidate is an error. Generated input projections and frozen host capability
272
+ models are construction APIs, not wire decode entrypoints; their canonical wire
273
+ values are validated at the dispatch/parse boundary. Direct dictionary
247
274
  mutation, standard-library `json.loads`, TypedDict annotations, and type assertions
248
275
  are not SDK validation entrypoints. Re-parse after manually mutating a mapping.
249
276
 
250
- Nested model attributes expose declared protocol fields. For example, `capability.Capabilities(effects=["modify"], modify={}).modify.input` is `None` when that grant is absent. Family queries are available on generic and per-occurrence capability models.
277
+ Nested model attributes expose declared protocol fields. For example, `Capabilities(effects=["modify"], modify={}).modify.input` is `None` when that grant is absent. Family queries are available on generic and per-occurrence capability models.
251
278
 
252
- Constructor aliases cannot silently overwrite wire keys. Supplying both
253
- `tool_name=` and `toolName=` raises `TypeError`, even if the values agree. For
254
- optional/defaulted fields, a lone wire spelling (for example `addressForm=` or
255
- `protocolVersion=`) is used and validated rather than replaced by a default.
256
- Required constructor parameters use their documented Python spelling;
257
- use `from_dict` to decode complete wire-keyed objects. In `from_dict`, distinct
258
- keys such as `toolName` and `tool_name` remain distinct wire/extension keys.
279
+ Use the documented Python spelling for constructor parameters. Use `from_dict`
280
+ to decode complete wire-keyed objects. In `from_dict`, distinct keys such as
281
+ `toolName` and `tool_name` remain distinct wire/extension keys.
259
282
 
260
283
  ### Owned attachments
261
284
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "agenthooksprotocol"
7
- version = "0.4.1"
7
+ version = "0.6.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"
@@ -9,6 +9,7 @@ from . import (
9
9
  effect,
10
10
  event,
11
11
  generated,
12
+ wire,
12
13
  path,
13
14
  registration,
14
15
  subscription,
@@ -29,7 +30,7 @@ from ._hooks import (
29
30
  PendingInvocation as PendingInvocation,
30
31
  HooksClosedError as HooksClosedError,
31
32
  )
32
- from ._outcomes import SchemaCandidate as SchemaCandidate
33
+ from ._host_metadata import HostManifestMetadata as HostManifestMetadata
33
34
  from .permission import Permission as Permission
34
35
  from .content import (
35
36
  OwnedContentSource as OwnedContentSource,
@@ -46,7 +47,6 @@ from .runtime import (
46
47
  OperationCancelledError as OperationCancelledError,
47
48
  )
48
49
 
49
- wire = generated
50
50
 
51
51
  __all__ = list(_model_names) + [
52
52
  "Attachment",
@@ -55,6 +55,7 @@ __all__ = list(_model_names) + [
55
55
  "OwnedContentSource",
56
56
  "ContentSources",
57
57
  "Permission",
58
+ "HostManifestMetadata",
58
59
  "state",
59
60
  "candidate",
60
61
  "diagnostics",
@@ -72,7 +73,6 @@ __all__ = list(_model_names) + [
72
73
  "Hooks",
73
74
  "HookResult",
74
75
  "SettlementDecodeError",
75
- "SchemaCandidate",
76
76
  "PendingInvocation",
77
77
  "ProtocolError",
78
78
  "Codec",
@@ -19,11 +19,8 @@ from typing import Any, TYPE_CHECKING
19
19
  from .runtime import OperationCancelledError, ProtocolError, _json_equal
20
20
 
21
21
  if TYPE_CHECKING:
22
- from .attachment import Attachment
23
22
  from .generated import ContentUploadReceipt
24
23
 
25
- Reference = dict[str, Any]
26
- Resolver = Callable[[Reference], Awaitable[bytes]]
27
24
  Uploader = Callable[[bytes], Awaitable["ContentUploadReceipt"]]
28
25
 
29
26
 
@@ -271,12 +268,9 @@ class ContentContext:
271
268
  def __init__(
272
269
  self,
273
270
  *,
274
- resolve: Resolver | None = None,
275
- upload: Uploader | None = None,
276
271
  bindings: Mapping[str, tuple[str | int, ...]],
277
272
  principal: str,
278
273
  original_request: dict[str, Any] | None = None,
279
- attachments: Mapping[str, Attachment] | None = None,
280
274
  ) -> None:
281
275
  if not principal or not isinstance(principal, str):
282
276
  raise ProtocolError("Authenticated content principal is required")
@@ -288,12 +282,9 @@ class ContentContext:
288
282
  for path in bindings.values()
289
283
  ):
290
284
  raise ProtocolError("Explicit nonempty content paths are required")
291
- self.resolve = resolve
292
- self.upload = upload
293
285
  self.bindings = {key: tuple(path) for key, path in bindings.items()}
294
286
  self.principal = principal
295
287
  self.original_request = deepcopy(original_request)
296
- self.attachments = dict(attachments or {})
297
288
  self._identities: dict[str, tuple[int, str]] = {}
298
289
 
299
290
  async def prepare(self, request: dict[str, Any], validator: Any) -> PreparedContent:
@@ -769,10 +760,6 @@ class ContentSources:
769
760
  self.bindings, self._slots, self._item_metadata = bindings, slots, metadata
770
761
  return previous - set(bindings.values())
771
762
 
772
- def edit_context(self, event, backend, upload, context):
773
- # Binary owners are independent of inline text/JSON settlement.
774
- return context
775
-
776
763
  async def project(
777
764
  self,
778
765
  event: dict[str, Any],