agenthooksprotocol 0.6.0__tar.gz → 0.7.0__tar.gz

{agenthooksprotocol-0.6.0/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agenthooksprotocol
-Version: 0.6.0
+Version: 0.7.0
 Summary: Official non-normative Python SDK for the Agent Hooks Protocol
 Author: Agent Hooks Protocol maintainers
 License: 
@@ -250,13 +250,18 @@ with open("hooks.json") as file:
     config = json.load(file)
 
 async def review(existing_arguments):
-    async with Hooks(config, source="urn:example:harness", capabilities=capability.HostCapabilities(
-        tool_before=capability.ToolBeforeCapabilities(
-            intercept=capability.ToolBeforeIntercept(
-                allow=True, deny=True, modify_input=capability.Modify.REPLACE,
+    async with Hooks(
+        config,
+        source="urn:example:harness",
+        harness=event.Harness(name="example", version="1"),
+        capabilities=capability.HostCapabilities(
+            tool_before=capability.ToolBeforeCapabilities(
+                intercept=capability.ToolBeforeIntercept(
+                    allow=True, deny=True, modify_input=capability.Modify.REPLACE,
+                ),
             ),
         ),
-    )) as hooks:
+    ) as hooks:
         result = await hooks.tool_before(event.ToolBeforeInput(
             call_id="call-1", name="read_file", input=existing_arguments,
             path="native", origin="native",
@@ -264,7 +269,7 @@ async def review(existing_arguments):
         return result  # Host validation and authorization still precede execution.
 ```
 
-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.
+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.
 
 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.
 
@@ -344,11 +349,11 @@ Registered stdio backends start with a minimal base environment rather than the
 
 `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.
 
-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.
+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.
 
 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.
 
-`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.
+`await hooks.session_start(event.SessionStartInput(session=..., trigger="startup", permission_mode="default", items=[]))` needs only occurrence-specific host facts. The SDK supplies `manifest`, `harness`, `type`, and `source`, and supplies `id`/`time` when absent; `event_id=` takes precedence over a supplied ID. Named host inputs do not expose harness identity; the constructor supplies it. 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.
 
 ## Backend servers
 

{agenthooksprotocol-0.6.0 → agenthooksprotocol-0.7.0}/README.md

@@ -26,13 +26,18 @@ with open("hooks.json") as file:
     config = json.load(file)
 
 async def review(existing_arguments):
-    async with Hooks(config, source="urn:example:harness", capabilities=capability.HostCapabilities(
-        tool_before=capability.ToolBeforeCapabilities(
-            intercept=capability.ToolBeforeIntercept(
-                allow=True, deny=True, modify_input=capability.Modify.REPLACE,
+    async with Hooks(
+        config,
+        source="urn:example:harness",
+        harness=event.Harness(name="example", version="1"),
+        capabilities=capability.HostCapabilities(
+            tool_before=capability.ToolBeforeCapabilities(
+                intercept=capability.ToolBeforeIntercept(
+                    allow=True, deny=True, modify_input=capability.Modify.REPLACE,
+                ),
             ),
         ),
-    )) as hooks:
+    ) as hooks:
         result = await hooks.tool_before(event.ToolBeforeInput(
             call_id="call-1", name="read_file", input=existing_arguments,
             path="native", origin="native",
@@ -40,7 +45,7 @@ async def review(existing_arguments):
         return result  # Host validation and authorization still precede execution.
 ```
 
-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.
+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.
 
 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.
 
@@ -120,11 +125,11 @@ Registered stdio backends start with a minimal base environment rather than the
 
 `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.
 
-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.
+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.
 
 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.
 
-`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.
+`await hooks.session_start(event.SessionStartInput(session=..., trigger="startup", permission_mode="default", items=[]))` needs only occurrence-specific host facts. The SDK supplies `manifest`, `harness`, `type`, and `source`, and supplies `id`/`time` when absent; `event_id=` takes precedence over a supplied ID. Named host inputs do not expose harness identity; the constructor supplies it. 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.
 
 ## Backend servers
 

{agenthooksprotocol-0.6.0 → agenthooksprotocol-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agenthooksprotocol"
-version = "0.6.0"
+version = "0.7.0"
 description = "Official non-normative Python SDK for the Agent Hooks Protocol"
 readme = "README.md"
 requires-python = ">=3.11"

{agenthooksprotocol-0.6.0 → agenthooksprotocol-0.7.0}/src/agenthooksprotocol/_hooks.py

@@ -11,7 +11,7 @@ from typing import Any, Callable, Generic, Mapping, TypeVar, cast, overload
 from types import TracebackType
 from .codec import ValueCodecs, Codec, Candidate, _decode_preserving
 from .response import ContextualResponse
-from .event import Event, EventType
+from .event import Event, EventType, Harness
 from .capability import HostCapabilities
 from ._host_metadata import HostManifestMetadata
 from . import _models as models
@@ -648,6 +648,7 @@ class Hooks(BoundaryMixin):
         config: dict[str, Any],
         *,
         source: str,
+        harness: Harness,
         capabilities: HostCapabilities,
         manifest_metadata: HostManifestMetadata | None = None,
         transport: Any = None,
@@ -665,6 +666,7 @@ class Hooks(BoundaryMixin):
         self._configure(
             config,
             source=source,
+            harness=harness,
             declarations=capabilities.to_wire(),
             manifest_metadata=manifest_metadata,
             transport=transport,
@@ -679,6 +681,7 @@ class Hooks(BoundaryMixin):
         config: dict[str, Any],
         *,
         source: str,
+        harness: Harness,
         declarations: dict[EventType, Any],
         manifest_metadata: HostManifestMetadata | None = None,
         transport: Any = None,
@@ -707,6 +710,15 @@ class Hooks(BoundaryMixin):
             or not FormatChecker().conforms(source, "uri")
         ):
             raise ProtocolError("source must be an absolute URI")
+        if not isinstance(harness, Harness):
+            raise TypeError("harness must be Harness")
+        identity = deepcopy(dict(harness))
+        common = self.validator.validators["common.schema.json"]
+        if not common.evolve(
+            schema={"$ref": common.schema["$id"] + "#/$defs/harness"}
+        ).is_valid(identity):
+            raise ProtocolError("harness must contain canonical name and version")
+        self._harness = identity
         self._pending: WeakSet[PendingInvocation] = WeakSet()
         self.config = deepcopy(config)
         self.source = source
@@ -950,6 +962,8 @@ class Hooks(BoundaryMixin):
     ) -> None:
         if event["source"] != self.source:
             raise ProtocolError("Occurrence source conflicts with configured source")
+        if not _json_equal(event["harness"], self._harness):
+            raise ProtocolError("Occurrence harness conflicts with configured harness")
         declaration = self.capabilities.get(event["type"])
         if declaration is None or mode not in declaration["modes"]:
             raise ProtocolError("Occurrence event or delivery mode was not advertised")
@@ -1199,6 +1213,8 @@ class Hooks(BoundaryMixin):
         event = deepcopy(input.to_wire() if hasattr(input, "to_wire") else input)
         if not isinstance(event, dict):
             raise TypeError("Event input must be a canonical event payload object")
+        if "harness" in event and not _json_equal(event["harness"], self._harness):
+            raise ProtocolError("Occurrence harness conflicts with configured harness")
         from ._content import normalized_content_slots, normalized_values
 
         paths, _ = normalized_content_slots().get(event_name, ((), ()))
@@ -1218,6 +1234,7 @@ class Hooks(BoundaryMixin):
         event.update(
             id=event_id if event_id is not None else event.get("id", str(uuid4())),
             source=self.source,
+            harness=deepcopy(self._harness),
             type=event_name,
             time=event.get("time", datetime.now(timezone.utc).isoformat()),
         )

{agenthooksprotocol-0.6.0 → agenthooksprotocol-0.7.0}/src/agenthooksprotocol/_interop_hooks.py

@@ -6,7 +6,7 @@ uses the same validated core without making wire mappings a public Hooks input.
 
 from typing import Any, cast, get_args
 
-from .event import EventType
+from .event import EventType, Harness
 from .runtime import ProtocolError
 
 from ._hooks import Hooks
@@ -16,6 +16,7 @@ def _hooks_for_wire(
     config: dict[str, Any],
     *,
     source: str,
+    harness: Harness,
     declarations: dict[str, Any],
     transport: Any,
 ) -> Hooks:
@@ -25,6 +26,7 @@ def _hooks_for_wire(
     hooks._configure(
         config,
         source=source,
+        harness=harness,
         declarations=cast(dict[EventType, Any], declarations),
         transport=transport,
     )