agenthooksprotocol 0.7.1__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.7.1/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.9.0}/PKG-INFO +19 -2
  2. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/README.md +18 -1
  3. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/pyproject.toml +1 -1
  4. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_hooks.py +63 -0
  5. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/__init__.py +43 -4
  6. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/ahp-codegen.lock.json +4 -4
  7. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/auth.py +44 -11
  8. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/generated.py +19 -2
  9. agenthooksprotocol-0.9.0/src/agenthooksprotocol/headers.py +129 -0
  10. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/schemas.json +50 -2
  11. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0/src/agenthooksprotocol.egg-info}/PKG-INFO +19 -2
  12. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/SOURCES.txt +2 -0
  13. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_event_types.py +1 -0
  14. agenthooksprotocol-0.9.0/tests/test_registration_headers.py +527 -0
  15. agenthooksprotocol-0.9.0/tests/test_subscribes.py +177 -0
  16. agenthooksprotocol-0.7.1/tests/test_subscribes.py +0 -76
  17. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/LICENSE +0 -0
  18. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/setup.cfg +0 -0
  19. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/__init__.py +0 -0
  20. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_boundaries.py +0 -0
  21. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_content.py +0 -0
  22. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_diagnostics.py +0 -0
  23. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_elicitation.py +0 -0
  24. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_grants.py +0 -0
  25. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_host_metadata.py +0 -0
  26. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_interop_content.py +0 -0
  27. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_interop_hooks.py +0 -0
  28. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/capability.py +0 -0
  29. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/content.py +0 -0
  30. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/effect.py +0 -0
  31. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/event.py +0 -0
  32. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/registration.py +0 -0
  33. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/subscription.py +0 -0
  34. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/tool.py +0 -0
  35. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/transport.py +0 -0
  36. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_outcomes.py +0 -0
  37. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_validator.py +0 -0
  38. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/attachment.py +0 -0
  39. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/candidate.py +0 -0
  40. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/capability.py +0 -0
  41. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/catalogue.py +0 -0
  42. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/codec.py +0 -0
  43. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/compaction.py +0 -0
  44. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/content.py +0 -0
  45. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/contract.py +0 -0
  46. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/diagnostics.py +0 -0
  47. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/effect.py +0 -0
  48. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/elicitation.py +0 -0
  49. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/event.py +0 -0
  50. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/integrations/__init__.py +0 -0
  51. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/integrations/pydantic.py +0 -0
  52. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/interop.py +0 -0
  53. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle.py +0 -0
  54. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle_client.py +0 -0
  55. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle_server.py +0 -0
  56. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lineage.py +0 -0
  57. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/observation_chain.py +0 -0
  58. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/path.py +0 -0
  59. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/permission.py +0 -0
  60. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/py.typed +0 -0
  61. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/registration.py +0 -0
  62. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/response.py +0 -0
  63. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/runtime.py +0 -0
  64. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/__init__.py +0 -0
  65. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_admission.py +0 -0
  66. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_framing.py +0 -0
  67. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_handlers.py +0 -0
  68. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_json.py +0 -0
  69. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_slots.py +0 -0
  70. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/asgi.py +0 -0
  71. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/attachments.py +0 -0
  72. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/hooks.py +0 -0
  73. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/stdio.py +0 -0
  74. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/state.py +0 -0
  75. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/subscription.py +0 -0
  76. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/tool.py +0 -0
  77. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transport.py +0 -0
  78. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/__init__.py +0 -0
  79. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/http.py +0 -0
  80. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/stdio.py +0 -0
  81. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/wire.py +0 -0
  82. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/dependency_links.txt +0 -0
  83. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/requires.txt +0 -0
  84. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/top_level.txt +0 -0
  85. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_attachments.py +0 -0
  86. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_catalogue.py +0 -0
  87. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_codec.py +0 -0
  88. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_compaction.py +0 -0
  89. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_compaction_wire.py +0 -0
  90. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_consumer_outcomes.py +0 -0
  91. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_content.py +0 -0
  92. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_content_lifetime.py +0 -0
  93. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_content_receipts.py +0 -0
  94. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_correlated_core.py +0 -0
  95. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_declared_contracts.py +0 -0
  96. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_elicitation_adapter.py +0 -0
  97. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_fixture_public.py +0 -0
  98. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_handwritten_surface.py +0 -0
  99. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_harness_identity.py +0 -0
  100. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_host_metadata.py +0 -0
  101. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_inline_messages.py +0 -0
  102. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_integration.py +0 -0
  103. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_integration_edges.py +0 -0
  104. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_interop.py +0 -0
  105. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_lifecycle.py +0 -0
  106. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_lifecycle_auth.py +0 -0
  107. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_observation.py +0 -0
  108. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_observation_chain_transport.py +0 -0
  109. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_owned_content.py +0 -0
  110. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_owned_content_hooks.py +0 -0
  111. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_package.py +0 -0
  112. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_content.py +0 -0
  113. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_contract_surface.py +0 -0
  114. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_examples.py +0 -0
  115. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_hooks.py +0 -0
  116. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_server.py +0 -0
  117. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_registration_auth.py +0 -0
  118. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_safety.py +0 -0
  119. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_schema_corrections.py +0 -0
  120. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_sdk_unification.py +0 -0
  121. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_server_catch_all.py +0 -0
  122. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_server_error_codes.py +0 -0
  123. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_session_manifest.py +0 -0
  124. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_shared_materialization.py +0 -0
  125. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_stdio_env.py +0 -0
  126. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_stdio_transport.py +0 -0
  127. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_structural_facade.py +0 -0
  128. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_typed_capabilities.py +0 -0
  129. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_typed_contract_regressions.py +0 -0
  130. {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_upload_planning.py +0 -0
  131. {agenthooksprotocol-0.7.1 → 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.7.1
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
 
@@ -343,12 +343,29 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
343
343
 
344
344
  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.
345
345
 
346
+ HTTP registrations accept `transport.headers`, for example:
347
+
348
+ ```json
349
+ {"type":"http","url":"https://policy.example/hooks","headers":{"X-Tenant":"engineering","X-Api-Key":{"valueEnv":"POLICY_API_KEY"},"X-Gateway":{"valueRef":"vault/policy"}}}
350
+ ```
351
+
352
+ All valid HTTP field names are supported, including `Authorization`, `Cookie`, `Origin`, and protocol headers. Literal API keys and cookies are supported. Values must be safe HTTP field values (no CR, LF, or NUL); this HTTPX transport supports Latin-1 header bytes, including non-ASCII values such as `café`. There is no additional SDK header-size limit. Duplicate names are compared case-insensitively: the last property in configuration iteration order wins.
353
+
354
+ Transport defaults and authentication are applied first, then configured registration headers override them case-insensitively, including `Content-Type` and `Authorization`. Configured `Authorization`, whether literal or referenced, suppresses provider acquisition, discovery, challenges, and retries. A failed explicit secret lookup fails delivery; it never falls back to OAuth.
355
+
356
+ `valueEnv` and `valueRef` reuse the bearer secret lookup helper and `Hooks(..., resolve_credential=callback)` callback. The optional contextual `header_resolver.resolve(context)` API remains available for harnesses needing backend, destination, purpose, cancellation, and deadline context. Values resolve once per event or upload operation, are reused on an allowed authentication retry, and rotate on subsequent operations. Errors redact values and references.
357
+
358
+ Configured headers apply to both event POSTs and backend content uploads, overriding upload defaults and authentication as well. They are not installed globally on borrowed clients, discovery/token requests, or other backends. Existing transport redirect behavior is unchanged (SDK HTTP transports already disable automatic redirects). Custom injected transports retain responsibility for their transport contract.
359
+
360
+
346
361
  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.
347
362
 
348
363
  ## Static host manifest
349
364
 
350
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.
351
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
+
352
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.
353
370
 
354
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
 
@@ -119,12 +119,29 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
119
119
 
120
120
  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.
121
121
 
122
+ HTTP registrations accept `transport.headers`, for example:
123
+
124
+ ```json
125
+ {"type":"http","url":"https://policy.example/hooks","headers":{"X-Tenant":"engineering","X-Api-Key":{"valueEnv":"POLICY_API_KEY"},"X-Gateway":{"valueRef":"vault/policy"}}}
126
+ ```
127
+
128
+ All valid HTTP field names are supported, including `Authorization`, `Cookie`, `Origin`, and protocol headers. Literal API keys and cookies are supported. Values must be safe HTTP field values (no CR, LF, or NUL); this HTTPX transport supports Latin-1 header bytes, including non-ASCII values such as `café`. There is no additional SDK header-size limit. Duplicate names are compared case-insensitively: the last property in configuration iteration order wins.
129
+
130
+ Transport defaults and authentication are applied first, then configured registration headers override them case-insensitively, including `Content-Type` and `Authorization`. Configured `Authorization`, whether literal or referenced, suppresses provider acquisition, discovery, challenges, and retries. A failed explicit secret lookup fails delivery; it never falls back to OAuth.
131
+
132
+ `valueEnv` and `valueRef` reuse the bearer secret lookup helper and `Hooks(..., resolve_credential=callback)` callback. The optional contextual `header_resolver.resolve(context)` API remains available for harnesses needing backend, destination, purpose, cancellation, and deadline context. Values resolve once per event or upload operation, are reused on an allowed authentication retry, and rotate on subsequent operations. Errors redact values and references.
133
+
134
+ Configured headers apply to both event POSTs and backend content uploads, overriding upload defaults and authentication as well. They are not installed globally on borrowed clients, discovery/token requests, or other backends. Existing transport redirect behavior is unchanged (SDK HTTP transports already disable automatic redirects). Custom injected transports retain responsibility for their transport contract.
135
+
136
+
122
137
  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.
123
138
 
124
139
  ## Static host manifest
125
140
 
126
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.
127
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
+
128
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.
129
146
 
130
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.7.1"
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"
@@ -654,6 +654,7 @@ class Hooks(BoundaryMixin):
654
654
  transport: Any = None,
655
655
  resolve_credential: Any = None,
656
656
  auth_provider: Any = None,
657
+ header_resolver: Any = None,
657
658
  max_concurrent_uploads: int = 8,
658
659
  inherit_environment: bool = False,
659
660
  ) -> None:
@@ -672,6 +673,7 @@ class Hooks(BoundaryMixin):
672
673
  transport=transport,
673
674
  resolve_credential=resolve_credential,
674
675
  auth_provider=auth_provider,
676
+ header_resolver=header_resolver,
675
677
  max_concurrent_uploads=max_concurrent_uploads,
676
678
  inherit_environment=inherit_environment,
677
679
  )
@@ -687,6 +689,7 @@ class Hooks(BoundaryMixin):
687
689
  transport: Any = None,
688
690
  resolve_credential: Any = None,
689
691
  auth_provider: Any = None,
692
+ header_resolver: Any = None,
690
693
  max_concurrent_uploads: int = 8,
691
694
  inherit_environment: bool = False,
692
695
  ) -> None:
@@ -703,6 +706,17 @@ class Hooks(BoundaryMixin):
703
706
  self._upload_limiter = anyio.Semaphore(max_concurrent_uploads)
704
707
  self.validator = Validator()
705
708
  self._lineage = TaskLineage(self.validator)
709
+ from .headers import validate_headers
710
+
711
+ registered_backends = config.get("hooks", []) if isinstance(config, dict) else []
712
+ for backend in registered_backends if isinstance(registered_backends, list) else []:
713
+ transport_config = (
714
+ backend.get("transport", {}) if isinstance(backend, dict) else {}
715
+ )
716
+ if isinstance(transport_config, dict) and transport_config.get("type") == "http":
717
+ validate_headers(transport_config.get("headers", {}))
718
+ self._header_resolver = header_resolver
719
+ self._resolve_credential = resolve_credential
706
720
  self.validator.validate("registration", config)
707
721
  if (
708
722
  not isinstance(source, str)
@@ -781,6 +795,21 @@ class Hooks(BoundaryMixin):
781
795
  for subscription in backend["subscriptions"]
782
796
  )
783
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
+
784
813
  @property
785
814
  def manifest(self) -> dict[str, Any]:
786
815
  """Return a detached snapshot of the configured static host manifest."""
@@ -863,6 +892,38 @@ class Hooks(BoundaryMixin):
863
892
  if isinstance(self._injected, dict)
864
893
  else self._injected
865
894
  )
895
+ from .transports.http import HTTPTransport
896
+
897
+ config = backend["transport"]
898
+ if (
899
+ config["type"] == "http"
900
+ and config.get("headers")
901
+ and isinstance(transport, HTTPTransport)
902
+ ):
903
+ from .auth import AuthenticatedHTTPTransport
904
+
905
+ # Keep borrowed client lifetime and programmatic metadata,
906
+ # but do not bypass the registration's endpoint scope.
907
+ if transport.url != config["url"]:
908
+ raise ProtocolError("HTTP registration endpoint mismatch")
909
+ transport = AuthenticatedHTTPTransport(
910
+ config["url"],
911
+ backend=backend,
912
+ resolve_credential=(
913
+ self._resolve_credential
914
+ if self._resolve_credential is not None
915
+ else getattr(transport, "resolve_credential", None)
916
+ ),
917
+ client=transport._ready(),
918
+ headers=transport.headers,
919
+ auth_provider=getattr(
920
+ transport, "auth_provider", self._auth_provider
921
+ ),
922
+ header_resolver=self._header_resolver or getattr(
923
+ transport, "header_resolver", None
924
+ ),
925
+ validator=self.validator,
926
+ )
866
927
  else:
867
928
  config = backend["transport"]
868
929
  if config["type"] == "stdio":
@@ -882,7 +943,9 @@ class Hooks(BoundaryMixin):
882
943
  transport = AuthenticatedHTTPTransport(
883
944
  config["url"],
884
945
  backend=backend,
946
+ resolve_credential=self._resolve_credential,
885
947
  auth_provider=self._auth_provider,
948
+ header_resolver=self._header_resolver,
886
949
  validator=self.validator,
887
950
  )
888
951
  self._owned.append(transport)