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.
- {agenthooksprotocol-0.4.1/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.6.0}/PKG-INFO +49 -26
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/README.md +48 -25
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/pyproject.toml +1 -1
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/__init__.py +3 -3
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_content.py +0 -13
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/_grants.py +1965 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_hooks.py +145 -186
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/_host_metadata.py +133 -0
- agenthooksprotocol-0.4.1/src/agenthooksprotocol/content.py → agenthooksprotocol-0.6.0/src/agenthooksprotocol/_interop_content.py +4 -30
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/_interop_hooks.py +48 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/__init__.py +398 -1758
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/content.py +0 -10
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/event.py +2 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/tool.py +0 -2
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_outcomes.py +9 -8
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/ahp-codegen.lock.json +3 -3
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/capability.py +76 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/catalogue.py +43 -6
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/codec.py +2 -2
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/content.py +28 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/diagnostics.py +0 -3
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/effect.py +0 -275
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/event.py +1 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/generated.py +2 -1
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/integrations/pydantic.py +3 -3
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/interop.py +24 -26
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle_client.py +1 -1
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle_server.py +17 -27
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/observation_chain.py +3 -3
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/response.py +2 -2
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/runtime.py +20 -10
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/schemas.json +7 -0
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/__init__.py +10 -0
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/_admission.py +43 -0
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/_handlers.py +1063 -0
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/_slots.py +45 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/asgi.py +2 -6
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/hooks.py +268 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/stdio.py +4 -4
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/tool.py +0 -1
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/transports/stdio.py +297 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0/src/agenthooksprotocol.egg-info}/PKG-INFO +49 -26
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/SOURCES.txt +15 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_attachments.py +55 -25
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_compaction.py +11 -3
- agenthooksprotocol-0.6.0/tests/test_consumer_outcomes.py +398 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_content.py +1 -1
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_content_lifetime.py +4 -2
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_content_receipts.py +5 -2
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_correlated_core.py +52 -13
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_declared_contracts.py +226 -70
- agenthooksprotocol-0.6.0/tests/test_event_types.py +40 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_fixture_public.py +2 -2
- agenthooksprotocol-0.6.0/tests/test_handwritten_surface.py +125 -0
- agenthooksprotocol-0.6.0/tests/test_host_metadata.py +130 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_inline_messages.py +72 -34
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_lifecycle_auth.py +1 -1
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_owned_content_hooks.py +18 -4
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_content.py +174 -64
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_contract_surface.py +9 -3
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_examples.py +20 -1
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_hooks.py +61 -39
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_public_server.py +273 -30
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_sdk_unification.py +96 -36
- agenthooksprotocol-0.6.0/tests/test_server_catch_all.py +101 -0
- agenthooksprotocol-0.6.0/tests/test_server_error_codes.py +171 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_session_manifest.py +66 -28
- agenthooksprotocol-0.6.0/tests/test_stdio_env.py +153 -0
- agenthooksprotocol-0.6.0/tests/test_stdio_transport.py +132 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_structural_facade.py +148 -39
- agenthooksprotocol-0.6.0/tests/test_subscribes.py +65 -0
- agenthooksprotocol-0.6.0/tests/test_typed_capabilities.py +173 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_typed_contract_regressions.py +141 -39
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_upload_planning.py +35 -9
- agenthooksprotocol-0.4.1/src/agenthooksprotocol/_grants.py +0 -619
- agenthooksprotocol-0.4.1/src/agenthooksprotocol/capability.py +0 -155
- agenthooksprotocol-0.4.1/src/agenthooksprotocol/server/__init__.py +0 -8
- agenthooksprotocol-0.4.1/src/agenthooksprotocol/server/hooks.py +0 -166
- agenthooksprotocol-0.4.1/src/agenthooksprotocol/transports/stdio.py +0 -92
- agenthooksprotocol-0.4.1/tests/test_consumer_outcomes.py +0 -146
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/LICENSE +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/setup.cfg +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_boundaries.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_diagnostics.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_elicitation.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/capability.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/effect.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/registration.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/subscription.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/transport.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/attachment.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/auth.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/candidate.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/compaction.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/contract.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/elicitation.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/integrations/__init__.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lineage.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/path.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/permission.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/py.typed +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/registration.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_framing.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_json.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/attachments.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/state.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/subscription.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transport.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transports/__init__.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transports/http.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/wire.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/dependency_links.txt +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/requires.txt +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/top_level.txt +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_catalogue.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_codec.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_compaction_wire.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_elicitation_adapter.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_integration.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_integration_edges.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_interop.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_lifecycle.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_observation.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_observation_chain_transport.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_owned_content.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_package.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_registration_auth.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_safety.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_schema_corrections.py +0 -0
- {agenthooksprotocol-0.4.1 → agenthooksprotocol-0.6.0}/tests/test_shared_materialization.py +0 -0
{agenthooksprotocol-0.4.1/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.6.0}/PKG-INFO
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agenthooksprotocol
|
|
3
|
-
Version: 0.
|
|
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.
|
|
255
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
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 =
|
|
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
|
|
469
|
-
|
|
470
|
-
|
|
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, `
|
|
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
|
-
|
|
477
|
-
|
|
478
|
-
|
|
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.
|
|
31
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
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 =
|
|
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
|
|
245
|
-
|
|
246
|
-
|
|
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, `
|
|
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
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
|
|
@@ -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 .
|
|
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],
|