@inneranimalmedia/agentsam-sdk 2.6.8 → 2.6.10

package/python/agentsam_sdk/hooks/__init__.py

@@ -0,0 +1,32 @@
+"""Portable AgentSam lifecycle hooks."""
+from .adapters import callback_adapter, command_adapter, http_adapter
+from .contracts import (
+    ERROR_HANDLING_DECISIONS,
+    FAILURE_MODES,
+    HOOK_EVENTS,
+    HOOK_PROTOCOL_SCHEMA,
+    HOOK_RECEIPT_SCHEMA,
+    PERMISSION_DECISIONS,
+    HookEnvelope,
+    HookOutput,
+    normalize_event,
+)
+from .runtime import HookDefinition, HookExecutionError, HookRuntime
+
+__all__ = [
+    "ERROR_HANDLING_DECISIONS",
+    "FAILURE_MODES",
+    "HOOK_EVENTS",
+    "HOOK_PROTOCOL_SCHEMA",
+    "HOOK_RECEIPT_SCHEMA",
+    "PERMISSION_DECISIONS",
+    "HookDefinition",
+    "HookEnvelope",
+    "HookExecutionError",
+    "HookOutput",
+    "HookRuntime",
+    "callback_adapter",
+    "command_adapter",
+    "http_adapter",
+    "normalize_event",
+]

package/python/agentsam_sdk/hooks/adapters.py

@@ -0,0 +1,132 @@
+"""Callback, subprocess, and HTTP ports for AgentSam Hooks."""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from .contracts import HookEnvelope
+
+_PORTABLE_ENV_KEYS = (
+    "PATH", "Path", "PATHEXT", "SYSTEMROOT", "WINDIR", "HOME", "USERPROFILE",
+    "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL",
+)
+
+
+def callback_adapter(handler: Callable[[Mapping[str, Any], Mapping[str, Any], HookEnvelope], Any]):
+    async def invoke(envelope: HookEnvelope):
+        result = handler(envelope.input, envelope.invocation, envelope)
+        if hasattr(result, "__await__"):
+            return await result
+        return result
+    return invoke
+
+
+def command_adapter(
+    command: str,
+    args: list[str] | None = None,
+    *,
+    cwd: str | None = None,
+    env: Mapping[str, str] | None = None,
+    inherit_environment: bool = False,
+    timeout_ms: int = 10_000,
+    max_output_bytes: int = 1_048_576,
+):
+    if not str(command).strip():
+        raise ValueError("hook_command_required")
+    configured_args = [str(value) for value in (args or [])]
+    environment = dict(os.environ) if inherit_environment else {
+        key: os.environ[key] for key in _PORTABLE_ENV_KEYS if key in os.environ
+    }
+    environment.update({str(key): str(value) for key, value in (env or {}).items()})
+
+    async def invoke(envelope: HookEnvelope):
+        try:
+            process = await asyncio.create_subprocess_exec(
+                command, *configured_args,
+                cwd=cwd or envelope.cwd,
+                env=environment,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except Exception as error:
+            failure = RuntimeError(f"hook_command_spawn_failed:{command}:{error}")
+            failure.__cause__ = error
+            raise failure
+        payload = (json.dumps(envelope.to_dict(), separators=(",", ":")) + "\n").encode()
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(payload), timeout=timeout_ms / 1000)
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise TimeoutError(f"hook_command_timeout:{command}:{timeout_ms}")
+        if len(stdout) + len(stderr) > max_output_bytes:
+            raise RuntimeError(f"hook_command_output_limit_exceeded:{command}:{max_output_bytes}")
+        if process.returncode != 0:
+            detail = stderr.decode(errors="replace").strip()[:512]
+            raise RuntimeError(f"hook_command_failed:{command}:exit={process.returncode}:{detail}")
+        lines = [line for line in stdout.decode().splitlines() if line.strip()]
+        if not lines:
+            return None
+        try:
+            return json.loads(lines[-1])
+        except json.JSONDecodeError as error:
+            raise RuntimeError(f"hook_command_invalid_json:{command}:{error}") from error
+
+    return invoke
+
+
+def http_adapter(
+    url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    timeout_ms: int = 10_000,
+    max_response_bytes: int = 1_048_576,
+):
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"unsupported_hook_http_protocol:{parsed.scheme}")
+    if parsed.username or parsed.password:
+        raise ValueError("hook_http_url_must_not_contain_credentials")
+    configured_headers = {"Accept": "application/json", "Content-Type": "application/json", **dict(headers or {})}
+
+    def failure(message: str, cause: BaseException) -> RuntimeError:
+        error = RuntimeError(message)
+        error.adapter = "http"
+        error.protocol = "http"
+        error.transport = parsed.scheme
+        error.__cause__ = cause
+        return error
+
+    def request(envelope: HookEnvelope):
+        payload = json.dumps(envelope.to_dict(), separators=(",", ":")).encode()
+        req = urllib.request.Request(url, data=payload, headers=configured_headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_ms / 1000) as response:
+                body = response.read(max_response_bytes + 1)
+        except urllib.error.HTTPError as error:
+            detail = error.read(512).decode(errors="replace")
+            raise failure(f"hook_http_failed:{error.code}:{detail}", error)
+        except (urllib.error.URLError, TimeoutError) as error:
+            detail = str(getattr(error, "reason", error))
+            reason = "hook_http_timeout" if "timed out" in detail.lower() or isinstance(getattr(error, "reason", None), TimeoutError) else "hook_http_request_failed"
+            raise failure(f"{reason}:{detail}", error)
+        if len(body) > max_response_bytes:
+            raise failure(f"hook_http_response_limit_exceeded:{max_response_bytes}", RuntimeError("response limit exceeded"))
+        if not body.strip():
+            return None
+        try:
+            return json.loads(body)
+        except json.JSONDecodeError as error:
+            raise failure(f"hook_http_invalid_json:{error}", error)
+
+    async def invoke(envelope: HookEnvelope):
+        return await asyncio.to_thread(request, envelope)
+
+    return invoke

package/python/agentsam_sdk/hooks/contracts.py

@@ -0,0 +1,121 @@
+"""Language-neutral AgentSam hook protocol models.
+
+The wire contract uses snake_case and JSON-compatible values so the same hook
+can run in-process, as a subprocess, or behind HTTP in any SDK language.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Mapping, Optional
+
+HOOK_PROTOCOL_SCHEMA = "agentsam.hook.v1"
+HOOK_RECEIPT_SCHEMA = "agentsam.hook.receipt.v1"
+HOOK_EVENTS = (
+    "session_start", "session_end", "user_prompt_submitted", "user_prompt_transformed",
+    "pre_model_use", "post_model_use", "pre_tool_use", "post_tool_use",
+    "post_tool_use_failure", "error_occurred", "agent_stop", "subagent_start", "subagent_stop",
+)
+PERMISSION_DECISIONS = ("allow", "deny", "ask")
+ERROR_HANDLING_DECISIONS = ("retry", "skip", "abort")
+FAILURE_MODES = ("open", "closed", "error")
+
+
+def normalize_event(value: str) -> str:
+    source = str(value or "").strip()
+    if source in HOOK_EVENTS:
+        return source
+    if source.startswith("on") and len(source) > 2:
+        source = source[2:3].lower() + source[3:]
+    normalized = ""
+    for character in source:
+        if character.isupper():
+            normalized += "_" + character.lower()
+        else:
+            normalized += character
+    if normalized in HOOK_EVENTS:
+        return normalized
+    raise ValueError(f"unsupported_hook_event:{value or '<missing>'}")
+
+
+@dataclass(frozen=True)
+class HookEnvelope:
+    hook: str
+    timestamp: int
+    cwd: str
+    invocation: Mapping[str, Any] = field(default_factory=dict)
+    input: Mapping[str, Any] = field(default_factory=dict)
+    schema: str = HOOK_PROTOCOL_SCHEMA
+
+    def __post_init__(self) -> None:
+        normalize_event(self.hook)
+        if self.timestamp < 0:
+            raise ValueError("hook_timestamp_must_be_non_negative")
+        allowed = {"session_id", "run_id", "turn_id", "message_id", "agent_id", "parent_agent_id", "source", "metadata"}
+        unknown = set(self.invocation) - allowed
+        if unknown:
+            raise ValueError(f"unsupported_hook_invocation_field:{sorted(unknown)[0]}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "HookEnvelope":
+        if value.get("schema") != HOOK_PROTOCOL_SCHEMA:
+            raise ValueError(f"unsupported_hook_schema:{value.get('schema')}")
+        return cls(
+            hook=normalize_event(str(value.get("hook", ""))),
+            timestamp=int(value.get("timestamp", 0)),
+            cwd=str(value.get("cwd", "")),
+            invocation=dict(value.get("invocation") or {}),
+            input=dict(value.get("input") or {}),
+        )
+
+
+@dataclass(frozen=True)
+class HookOutput:
+    permission_decision: Optional[str] = None
+    permission_decision_reason: Optional[str] = None
+    modified_args: Optional[Mapping[str, Any]] = None
+    modified_request: Optional[Mapping[str, Any]] = None
+    modified_result: Any = None
+    modified_prompt: Optional[str] = None
+    modified_transformed_prompt: Optional[str] = None
+    modified_config: Optional[Mapping[str, Any]] = None
+    additional_context: Optional[str] = None
+    suppress_output: Optional[bool] = None
+    error_handling: Optional[str] = None
+    retry_count: Optional[int] = None
+    user_notification: Optional[str] = None
+    decision: Optional[str] = None
+    reason: Optional[str] = None
+    cleanup_actions: Optional[list[str]] = None
+    session_summary: Optional[str] = None
+    metadata: Optional[Mapping[str, Any]] = None
+    _present_fields: frozenset[str] = field(default_factory=frozenset, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if self.permission_decision and self.permission_decision not in PERMISSION_DECISIONS:
+            raise ValueError(f"invalid_permission_decision:{self.permission_decision}")
+        if self.error_handling and self.error_handling not in ERROR_HANDLING_DECISIONS:
+            raise ValueError(f"invalid_error_handling:{self.error_handling}")
+        if self.decision and self.decision not in ("allow", "block"):
+            raise ValueError(f"invalid_stop_decision:{self.decision}")
+        if self.retry_count is not None and not 0 <= self.retry_count <= 10:
+            raise ValueError("retry_count_must_be_between_0_and_10")
+
+    def to_dict(self) -> dict[str, Any]:
+        values = asdict(self)
+        values.pop("_present_fields", None)
+        return {
+            key: value for key, value in values.items()
+            if value is not None or key in self._present_fields
+        }
+
+    @classmethod
+    def from_value(cls, value: Optional[Mapping[str, Any] | "HookOutput"]) -> "HookOutput":
+        if value is None:
+            return cls()
+        if isinstance(value, cls):
+            return value
+        fields = dict(value)
+        return cls(**fields, _present_fields=frozenset(fields))

package/python/agentsam_sdk/hooks/runtime.py

@@ -0,0 +1,253 @@
+"""Async reference runtime for AgentSam hooks."""
+from __future__ import annotations
+
+import asyncio
+import copy
+import inspect
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Mapping, Optional
+
+from ..errors import error_policy, normalize_error_reason
+from .contracts import FAILURE_MODES, HookEnvelope, HookOutput, normalize_event
+
+HookHandler = Callable[[HookEnvelope], Optional[HookOutput | Mapping[str, Any]] | Awaitable[Optional[HookOutput | Mapping[str, Any]]]]
+
+
+@dataclass(frozen=True)
+class HookDefinition:
+    id: str
+    handler: HookHandler
+    priority: float = 100
+    timeout_ms: int = 10_000
+    failure_mode: Optional[str] = None
+    enabled: bool = True
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+class HookExecutionError(RuntimeError):
+    def __init__(self, definition: HookDefinition, cause: BaseException):
+        super().__init__(f"hook_execution_failed:{definition.id}:{cause}")
+        self.code = "AGENTSAM_HOOK_EXECUTION_FAILED"
+        self.reason = normalize_error_reason(getattr(cause, "reason", None), str(cause), getattr(cause, "code", None))
+        self.error_code = error_policy(self.reason)["code"]
+        self.hook_id = definition.id
+        self.__cause__ = cause
+
+
+def _safe_error(error: BaseException) -> str:
+    message = str(error)
+    message = re.sub(r"(authorization\s*[:=]\s*bearer\s+)[^\s,;]+", r"\1[REDACTED]", message, flags=re.I)
+    message = re.sub(r"((?:api[_-]?key|password|secret|token)\s*[:=]\s*)[^\s,;]+", r"\1[REDACTED]", message, flags=re.I)
+    return message[:512]
+
+
+def _fingerprint(*values: object) -> str:
+    text = "\x1f".join(str(value or "").strip() for value in values).encode()
+    value = 0xCBF29CE484222325
+    for byte in text:
+        value ^= byte
+        value = (value * 0x100000001B3) & 0xFFFFFFFFFFFFFFFF
+    return f"err_{value:016x}"
+
+
+def _canonical_failure(definition: HookDefinition, event: str, error: BaseException) -> tuple[dict[str, Any], dict[str, Any]]:
+    reason = normalize_error_reason(getattr(error, "reason", None), str(error), getattr(error, "code", None))
+    if reason == "hook_handler_failed" and isinstance(error, (TimeoutError, asyncio.TimeoutError)):
+        reason = "hook_handler_timeout"
+    if reason.startswith(("mcp_", "lsp_")):
+        hook_specific = normalize_error_reason(f"hook_{reason}")
+        if hook_specific != "hook_handler_failed":
+            reason = hook_specific
+    policy = error_policy(reason)
+    is_post = event in ("post_tool_use", "post_model_use")
+    mode = definition.failure_mode or _default_failure_mode(event)
+    behavior = "fail_closed" if mode == "closed" else "fail_open" if mode == "open" else "no_replay" if is_post else "abort"
+    side_effect = "confirmed_applied" if is_post else "unknown" if event == "post_tool_use_failure" else "not_started"
+    adapter = str(getattr(error, "adapter", "") or definition.metadata.get("adapter_type", "") or "").strip() or None
+    if adapter is None:
+        adapter = next((name for name in ("http", "mcp", "lsp", "command") if reason.startswith(f"hook_{name}_")), None)
+    protocol = str(getattr(error, "protocol", "") or ("agentsam.hook.v1" if adapter == "command" else adapter or "")).strip() or None
+    transport = str(getattr(error, "transport", "") or ("process" if adapter == "command" else "")).strip() or None
+    feature = f"hooks.{event}"
+    message = _safe_error(error)
+    retryable = bool(policy["retryable"]) and not is_post and behavior != "fail_closed"
+    canonical = {
+        "error_code": policy["code"], "reason": reason, "domain": policy["domain"],
+        "failure_class": policy["failure_class"], "stage": policy["default_stage"], "feature": feature,
+        "failure_behavior": behavior, "retryable": retryable, "side_effect_state": side_effect,
+        "adapter": adapter, "protocol": protocol, "transport": transport,
+        "fingerprint": _fingerprint(
+            policy["code"], reason, policy["domain"], policy["failure_class"], policy["default_stage"],
+            feature, behavior, side_effect, adapter, protocol, transport, definition.id,
+        ),
+        "message": message,
+    }
+    native = {
+        "code": str(getattr(error, "code", ""))[:128] or None,
+        "exception_type": type(error).__name__[:128],
+        "message": message,
+    }
+    return canonical, native
+
+
+def _default_failure_mode(event: str) -> str:
+    return "closed" if event in ("pre_tool_use", "pre_model_use") else "open"
+
+
+def _merge_output(current: dict[str, Any], update: dict[str, Any]) -> None:
+    for key, value in update.items():
+        if key == "additional_context":
+            continue
+        if key == "suppress_output":
+            current[key] = bool(current.get(key)) or value is True
+        elif key == "retry_count":
+            current[key] = max(int(current.get(key, 0)), int(value))
+        elif key == "cleanup_actions":
+            current[key] = [*current.get(key, []), *value]
+        elif key == "modified_config":
+            current[key] = {**current.get(key, {}), **copy.deepcopy(value)}
+        else:
+            current[key] = copy.deepcopy(value)
+
+
+def _update_input(event: str, value: dict[str, Any], output: dict[str, Any]) -> None:
+    if "modified_args" in output:
+        value["tool_args"] = copy.deepcopy(output["modified_args"])
+    if "modified_request" in output:
+        value["request"] = copy.deepcopy(output["modified_request"])
+    if "modified_result" in output:
+        value["tool_result" if event == "post_tool_use" else "model_result"] = copy.deepcopy(output["modified_result"])
+    if "modified_prompt" in output:
+        value["prompt"] = output["modified_prompt"]
+    if "modified_transformed_prompt" in output:
+        value["transformed_prompt"] = output["modified_transformed_prompt"]
+    if "modified_config" in output:
+        value["config"] = {**value.get("config", {}), **copy.deepcopy(output["modified_config"])}
+
+
+def _terminal(event: str, output: dict[str, Any]) -> bool:
+    return (
+        event in ("pre_tool_use", "pre_model_use")
+        and output.get("permission_decision") in ("deny", "ask")
+    ) or (event == "agent_stop" and output.get("decision") == "block")
+
+
+class HookRuntime:
+    def __init__(self, *, clock: Callable[[], float] | None = None, on_receipt: Callable[[Mapping[str, Any]], Any] | None = None):
+        self._clock = clock or (lambda: time.time() * 1000)
+        self._on_receipt = on_receipt
+        self._registry: dict[str, list[HookDefinition]] = {}
+        self._sequence = 0
+
+    def register(self, event: str, definition: HookDefinition | HookHandler, **options: Any) -> "HookRuntime":
+        hook = normalize_event(event)
+        if not isinstance(definition, HookDefinition):
+            definition = HookDefinition(id=options.pop("id", f"{hook}:{self._sequence + 1}"), handler=definition, **options)
+        if definition.failure_mode and definition.failure_mode not in FAILURE_MODES:
+            raise ValueError(f"invalid_hook_failure_mode:{definition.failure_mode}")
+        if definition.timeout_ms < 1 or definition.timeout_ms > 600_000:
+            raise ValueError(f"invalid_hook_timeout_ms:{definition.timeout_ms}")
+        rows = self._registry.setdefault(hook, [])
+        if any(row.id == definition.id for row in rows):
+            raise ValueError(f"duplicate_hook_id:{definition.id}")
+        rows.append(definition)
+        rows.sort(key=lambda row: (row.priority, row.id))
+        self._sequence += 1
+        return self
+
+    def list(self, event: str | None = None) -> list[dict[str, Any]]:
+        rows = self._registry.get(normalize_event(event), []) if event else [row for group in self._registry.values() for row in group]
+        return [{
+            "id": row.id, "hook": next((hook for hook, group in self._registry.items() if row in group), None),
+            "priority": row.priority, "timeout_ms": row.timeout_ms,
+            "failure_mode": row.failure_mode, "enabled": row.enabled, "metadata": dict(row.metadata),
+        } for row in rows]
+
+    async def _observe(self, receipt: Mapping[str, Any]) -> None:
+        if self._on_receipt is None:
+            return
+        try:
+            result = self._on_receipt(receipt)
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            pass
+
+    async def dispatch(
+        self,
+        event: str,
+        input: Mapping[str, Any] | None = None,
+        invocation: Mapping[str, Any] | None = None,
+        *,
+        cwd: str | None = None,
+    ) -> dict[str, Any]:
+        hook = normalize_event(event)
+        working = copy.deepcopy(dict(input or {}))
+        invocation_value = copy.deepcopy(dict(invocation or {}))
+        combined: dict[str, Any] = {}
+        contexts: list[str] = []
+        receipts: list[dict[str, Any]] = []
+        errors: list[dict[str, Any]] = []
+
+        for definition in self._registry.get(hook, []):
+            if not definition.enabled:
+                continue
+            envelope = HookEnvelope(
+                hook=hook,
+                timestamp=int(self._clock()),
+                cwd=str(cwd or working.get("cwd") or os.getcwd()),
+                invocation=invocation_value,
+                input=copy.deepcopy(working),
+            )
+            started = int(self._clock())
+            try:
+                result = definition.handler(envelope)
+                if inspect.isawaitable(result):
+                    result = await asyncio.wait_for(result, timeout=definition.timeout_ms / 1000)
+                output = HookOutput.from_value(result).to_dict()
+                _update_input(hook, working, output)
+                _merge_output(combined, output)
+                if output.get("additional_context"):
+                    contexts.append(str(output["additional_context"]))
+                receipt = {
+                    "schema": "agentsam.hook.receipt.v1", "hook_id": definition.id, "hook": hook,
+                    "status": "completed", "started_at": started, "completed_at": int(self._clock()),
+                    "input_keys": sorted(envelope.input.keys()), "output_keys": sorted(output.keys()),
+                }
+                receipt["duration_ms"] = max(0, receipt["completed_at"] - started)
+                receipts.append(receipt)
+                await self._observe(receipt)
+                if _terminal(hook, output):
+                    break
+            except Exception as error:
+                completed = int(self._clock())
+                safe_error = _safe_error(error)
+                canonical, native_evidence = _canonical_failure(definition, hook, error)
+                receipt = {
+                    "schema": "agentsam.hook.receipt.v1", "hook_id": definition.id, "hook": hook,
+                    "status": "failed", "started_at": started, "completed_at": completed,
+                    "duration_ms": max(0, completed - started), "input_keys": sorted(envelope.input.keys()),
+                    "output_keys": [], "error": canonical, "native_evidence": native_evidence,
+                }
+                receipts.append(receipt)
+                errors.append({"hook_id": definition.id, "hook": hook, **canonical, "native_evidence": native_evidence})
+                await self._observe(receipt)
+                mode = definition.failure_mode or _default_failure_mode(hook)
+                if mode == "error":
+                    raise HookExecutionError(definition, error) from error
+                if mode == "closed":
+                    combined.update({
+                        "permission_decision": "deny",
+                        "permission_decision_reason": f"Hook '{definition.id}' failed closed: {safe_error}",
+                    })
+                    break
+
+        if contexts:
+            combined["additional_context"] = "\n\n".join(contexts)
+        return {
+            "schema": "agentsam.hook.dispatch.v1", "hook": hook,
+            "input": working, "output": combined, "receipts": receipts, "errors": errors,
+        }

package/python/tests/test_hooks.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import unittest
+
+from agentsam_sdk.errors import normalize_error_reason
+from agentsam_sdk.hooks import (
+    HOOK_PROTOCOL_SCHEMA,
+    HookDefinition,
+    HookOutput,
+    HookRuntime,
+    command_adapter,
+    normalize_event,
+)
+
+
+class HookContractTests(unittest.TestCase):
+    def test_protocol_contract_is_canonical(self):
+        self.assertEqual(HOOK_PROTOCOL_SCHEMA, "agentsam.hook.v1")
+        self.assertEqual(normalize_event("onPreToolUse"), "pre_tool_use")
+        self.assertEqual(HookOutput(permission_decision="allow").to_dict(), {"permission_decision": "allow"})
+        self.assertEqual(HookOutput.from_value({"modified_result": None}).to_dict(), {"modified_result": None})
+        self.assertEqual(HookOutput.from_value({"modified_config": {"auto_compact": False}}).to_dict(), {"modified_config": {"auto_compact": False}})
+        with self.assertRaisesRegex(ValueError, "invalid_permission_decision"):
+            HookOutput(permission_decision="maybe")
+        self.assertEqual(normalize_error_reason("AGENTSAM_HOOK_HTTP_FAILED"), "hook_http_request_failed")
+        self.assertEqual(normalize_error_reason("hook_command_invalid_json:node"), "hook_command_output_invalid")
+
+
+class HookRuntimeTests(unittest.IsolatedAsyncioTestCase):
+    async def test_composes_modified_arguments_and_context(self):
+        runtime = HookRuntime()
+        runtime.register("pre_tool_use", HookDefinition(
+            id="first", priority=10,
+            handler=lambda envelope: {
+                "permission_decision": "allow",
+                "modified_args": {**envelope.input["tool_args"], "first": True},
+                "additional_context": "first context",
+            },
+        ))
+        runtime.register("pre_tool_use", HookDefinition(
+            id="second", priority=20,
+            handler=lambda envelope: {
+                "modified_args": {**envelope.input["tool_args"], "second": True},
+                "additional_context": "second context",
+            },
+        ))
+        result = await runtime.dispatch("pre_tool_use", {
+            "tool_name": "read", "tool_args": {"value": 1},
+        }, {"session_id": "session-test"})
+        self.assertEqual(result["input"]["tool_args"], {"value": 1, "first": True, "second": True})
+        self.assertEqual(result["output"]["additional_context"], "first context\n\nsecond context")
+        self.assertEqual([row["hook_id"] for row in result["receipts"]], ["first", "second"])
+
+    async def test_session_config_patches_compose(self):
+        runtime = HookRuntime()
+        runtime.register("session_start", HookDefinition(
+            id="model", priority=10,
+            handler=lambda _: {"modified_config": {"model_key": "xai:grok-4"}},
+        ))
+        runtime.register("session_start", HookDefinition(
+            id="effort", priority=20,
+            handler=lambda _: {"modified_config": {"reasoning_effort": "high"}},
+        ))
+        result = await runtime.dispatch("session_start", {"config": {"auto_compact": True}})
+        self.assertEqual(result["input"]["config"], {
+            "auto_compact": True,
+            "model_key": "xai:grok-4",
+            "reasoning_effort": "high",
+        })
+
+    async def test_permission_hook_fails_closed(self):
+        runtime = HookRuntime()
+        def broken(_):
+            raise RuntimeError("policy unavailable")
+        runtime.register("pre_tool_use", HookDefinition(id="policy", handler=broken))
+        result = await runtime.dispatch("pre_tool_use", {"tool_name": "write", "tool_args": {}})
+        self.assertEqual(result["output"]["permission_decision"], "deny")
+        self.assertIn("failed closed", result["output"]["permission_decision_reason"])
+        error = result["receipts"][0]["error"]
+        self.assertEqual(error["error_code"], "INTERNAL")
+        self.assertEqual(error["reason"], "hook_handler_failed")
+        self.assertEqual(error["failure_behavior"], "fail_closed")
+        self.assertEqual(error["side_effect_state"], "not_started")
+        self.assertFalse(error["retryable"])
+
+    async def test_observer_receipt_preserves_timeout_and_applied_side_effect(self):
+        runtime = HookRuntime()
+        def broken(_):
+            raise TimeoutError("hook_lsp_timeout:rust")
+        runtime.register("post_tool_use", HookDefinition(id="observer", handler=broken))
+        result = await runtime.dispatch("post_tool_use", {"tool_name": "write", "tool_result": {"ok": True}})
+        error = result["receipts"][0]["error"]
+        self.assertEqual(error["error_code"], "DEADLINE_EXCEEDED")
+        self.assertEqual(error["reason"], "hook_lsp_timeout")
+        self.assertEqual(error["failure_behavior"], "fail_open")
+        self.assertEqual(error["side_effect_state"], "confirmed_applied")
+        self.assertFalse(error["retryable"])
+
+    async def test_command_adapter_uses_same_wire_envelope(self):
+        code = (
+            "import json,sys; e=json.load(sys.stdin); "
+            "print(json.dumps({'permission_decision': 'allow' if e['schema']=='agentsam.hook.v1' else 'deny'}))"
+        )
+        handler = command_adapter(sys.executable, ["-c", code], cwd=os.getcwd(), timeout_ms=2000)
+        runtime = HookRuntime()
+        runtime.register("pre_tool_use", HookDefinition(id="python", handler=handler))
+        result = await runtime.dispatch("pre_tool_use", {"tool_name": "read", "tool_args": {}})
+        self.assertEqual(result["output"]["permission_decision"], "allow")
+
+
+if __name__ == "__main__":
+    unittest.main()