hanzo-hooks 0.1.0__tar.gz

hanzo_hooks-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: hanzo-hooks
+Version: 0.1.0
+Summary: Shell hook runner for pre/post tool-use lifecycle events.
+Author-email: Hanzo Industries Inc <dev@hanzo.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/hanzoai/python-sdk
+Project-URL: Bug Tracker, https://github.com/hanzoai/python-sdk/issues
+Keywords: hanzo,hooks,tools,ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12

hanzo_hooks-0.1.0/hanzo_hooks/__init__.py

@@ -0,0 +1,6 @@
+"""hanzo-hooks: shell hook runner for pre/post tool-use lifecycle events."""
+
+from .runner import HookRunner
+from .types import HookConfig, HookEvent, HookRunResult
+
+__all__ = ["HookConfig", "HookEvent", "HookRunner", "HookRunResult"]

hanzo_hooks-0.1.0/hanzo_hooks/runner.py

@@ -0,0 +1,97 @@
+"""HookRunner: execute shell commands around tool invocations."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+from .types import HookConfig, HookEvent, HookRunResult
+
+
+class HookRunner:
+    __slots__ = ("_config",)
+
+    def __init__(self, config: HookConfig) -> None:
+        self._config = config
+
+    @classmethod
+    def from_settings(cls, path: str) -> HookRunner:
+        return cls(HookConfig.from_json(path))
+
+    def run_pre_tool_use(self, tool_name: str, tool_input: str) -> HookRunResult:
+        return self._run_commands(
+            HookEvent.PreToolUse, self._config.pre_tool_use, tool_name, tool_input,
+        )
+
+    def run_post_tool_use(
+        self, tool_name: str, tool_input: str, tool_output: str, is_error: bool = False,
+    ) -> HookRunResult:
+        return self._run_commands(
+            HookEvent.PostToolUse, self._config.post_tool_use,
+            tool_name, tool_input, tool_output=tool_output, is_error=is_error,
+        )
+
+    def _run_commands(
+        self, event: HookEvent, commands: list[str], tool_name: str, tool_input: str,
+        tool_output: str | None = None, is_error: bool = False,
+    ) -> HookRunResult:
+        if not commands:
+            return HookRunResult.allow()
+
+        try:
+            parsed_input = json.loads(tool_input)
+        except (json.JSONDecodeError, TypeError):
+            parsed_input = {"raw": tool_input}
+
+        payload = json.dumps({
+            "hook_event_name": event.value, "tool_name": tool_name,
+            "tool_input": parsed_input, "tool_input_json": tool_input,
+            "tool_output": tool_output, "tool_result_is_error": is_error,
+        })
+        env = {
+            "HOOK_EVENT": event.value, "HOOK_TOOL_NAME": tool_name,
+            "HOOK_TOOL_INPUT": tool_input, "HOOK_TOOL_IS_ERROR": "1" if is_error else "0",
+        }
+        if tool_output is not None:
+            env["HOOK_TOOL_OUTPUT"] = tool_output
+
+        messages: list[str] = []
+        for command in commands:
+            kind, msg = _run_one(command, event, tool_name, env, payload)
+            if kind == "allow":
+                if msg:
+                    messages.append(msg)
+            elif kind == "deny":
+                messages.append(msg or f"{event.value} hook denied tool `{tool_name}`")
+                return HookRunResult(denied=True, messages=messages)
+            else:
+                messages.append(msg)
+        return HookRunResult.allow(messages)
+
+
+def _run_one(
+    command: str, event: HookEvent, tool_name: str,
+    env: dict[str, str], payload: str,
+) -> tuple[str, str]:
+    """Returns (outcome_type, message). outcome_type: allow/deny/warn."""
+    args = ["cmd", "/C", command] if sys.platform == "win32" else ["sh", "-lc", command]
+    try:
+        proc = subprocess.run(
+            args, input=payload, capture_output=True, text=True,
+            env={**os.environ, **env},
+        )
+    except OSError as exc:
+        return ("warn", f"{event.value} hook `{command}` failed to start for `{tool_name}`: {exc}")
+
+    stdout, stderr = proc.stdout.strip(), proc.stderr.strip()
+    if proc.returncode == 0:
+        return ("allow", stdout)
+    if proc.returncode == 2:
+        return ("deny", stdout)
+    msg = f"Hook `{command}` exited with status {proc.returncode}; allowing tool execution to continue"
+    if stdout:
+        msg += f": {stdout}"
+    elif stderr:
+        msg += f": {stderr}"
+    return ("warn", msg)

hanzo_hooks-0.1.0/hanzo_hooks/types.py

@@ -0,0 +1,72 @@
+"""Types for the hook runner system."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class HookEvent(Enum):
+    PreToolUse = "PreToolUse"
+    PostToolUse = "PostToolUse"
+
+
+@dataclass(frozen=True, slots=True)
+class HookRunResult:
+    denied: bool
+    messages: list[str]
+
+    @classmethod
+    def allow(cls, messages: list[str] | None = None) -> HookRunResult:
+        return cls(denied=False, messages=messages or [])
+
+    def to_permission_outcome(self) -> object:
+        """Convert to hanzoai.protocols.PermissionOutcome if available.
+
+        Returns a duck-typed object with .allowed and .reason when the
+        hanzoai package is not installed, so callers can use it without
+        a hard dependency.
+        """
+        try:
+            from hanzoai.protocols import PermissionOutcome
+        except ImportError:
+            PermissionOutcome = None
+
+        if PermissionOutcome is not None:
+            if self.denied:
+                return PermissionOutcome.deny("; ".join(self.messages))
+            return PermissionOutcome.allow()
+
+        # Fallback: return a simple namespace matching the protocol.
+        if self.denied:
+            return _Outcome(allowed=False, reason="; ".join(self.messages))
+        return _Outcome(allowed=True, reason="")
+
+
+@dataclass(frozen=True, slots=True)
+class _Outcome:
+    """Minimal stand-in for PermissionOutcome when hanzoai is not installed."""
+    allowed: bool
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class HookConfig:
+    """Loadable from settings.json ``hooks`` key."""
+    pre_tool_use: list[str] = field(default_factory=list)
+    post_tool_use: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> HookConfig:
+        return cls(
+            pre_tool_use=list(d.get("pre_tool_use") or d.get("PreToolUse") or []),
+            post_tool_use=list(d.get("post_tool_use") or d.get("PostToolUse") or []),
+        )
+
+    @classmethod
+    def from_json(cls, path: str) -> HookConfig:
+        with open(path) as f:
+            data = json.load(f)
+        hooks = data.get("hooks", data)
+        return cls.from_dict(hooks)

hanzo_hooks-0.1.0/hanzo_hooks.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: hanzo-hooks
+Version: 0.1.0
+Summary: Shell hook runner for pre/post tool-use lifecycle events.
+Author-email: Hanzo Industries Inc <dev@hanzo.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/hanzoai/python-sdk
+Project-URL: Bug Tracker, https://github.com/hanzoai/python-sdk/issues
+Keywords: hanzo,hooks,tools,ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12

hanzo_hooks-0.1.0/hanzo_hooks.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+pyproject.toml
+hanzo_hooks/__init__.py
+hanzo_hooks/runner.py
+hanzo_hooks/types.py
+hanzo_hooks.egg-info/PKG-INFO
+hanzo_hooks.egg-info/SOURCES.txt
+hanzo_hooks.egg-info/dependency_links.txt
+hanzo_hooks.egg-info/top_level.txt
+tests/test_hooks.py

hanzo_hooks-0.1.0/hanzo_hooks.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hanzo_hooks-0.1.0/hanzo_hooks.egg-info/top_level.txt

@@ -0,0 +1 @@
+hanzo_hooks

hanzo_hooks-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hanzo-hooks"
+version = "0.1.0"
+description = "Shell hook runner for pre/post tool-use lifecycle events."
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Hanzo Industries Inc", email = "dev@hanzo.ai" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+keywords = ["hanzo", "hooks", "tools", "ai"]
+dependencies = []
+
+[project.urls]
+"Homepage" = "https://github.com/hanzoai/python-sdk"
+"Bug Tracker" = "https://github.com/hanzoai/python-sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["hanzo_hooks*"]

hanzo_hooks-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hanzo_hooks-0.1.0/tests/test_hooks.py

@@ -0,0 +1,161 @@
+"""Tests for hanzo_hooks."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+from hanzo_hooks import HookConfig, HookEvent, HookRunner, HookRunResult
+
+
+class TestHookEvent:
+    def test_values(self):
+        assert HookEvent.PreToolUse.value == "PreToolUse"
+        assert HookEvent.PostToolUse.value == "PostToolUse"
+
+
+class TestHookRunResult:
+    def test_allow(self):
+        r = HookRunResult.allow()
+        assert not r.denied
+        assert r.messages == []
+
+    def test_allow_with_messages(self):
+        r = HookRunResult.allow(["msg1", "msg2"])
+        assert not r.denied
+        assert r.messages == ["msg1", "msg2"]
+
+    def test_denied(self):
+        r = HookRunResult(denied=True, messages=["blocked"])
+        assert r.denied
+        assert r.messages == ["blocked"]
+
+    def test_to_permission_outcome_allow(self):
+        r = HookRunResult.allow()
+        outcome = r.to_permission_outcome()
+        assert outcome.allowed is True
+
+    def test_to_permission_outcome_deny(self):
+        r = HookRunResult(denied=True, messages=["reason A", "reason B"])
+        outcome = r.to_permission_outcome()
+        assert outcome.allowed is False
+        assert "reason A" in outcome.reason
+        assert "reason B" in outcome.reason
+
+
+class TestHookConfig:
+    def test_from_dict(self):
+        cfg = HookConfig.from_dict({
+            "pre_tool_use": ["echo pre"],
+            "post_tool_use": ["echo post"],
+        })
+        assert cfg.pre_tool_use == ["echo pre"]
+        assert cfg.post_tool_use == ["echo post"]
+
+    def test_from_dict_camel_case(self):
+        cfg = HookConfig.from_dict({
+            "PreToolUse": ["echo pre"],
+            "PostToolUse": ["echo post"],
+        })
+        assert cfg.pre_tool_use == ["echo pre"]
+        assert cfg.post_tool_use == ["echo post"]
+
+    def test_from_dict_empty(self):
+        cfg = HookConfig.from_dict({})
+        assert cfg.pre_tool_use == []
+        assert cfg.post_tool_use == []
+
+    def test_from_json(self):
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump({"hooks": {"pre_tool_use": ["echo hi"]}}, f)
+            f.flush()
+            cfg = HookConfig.from_json(f.name)
+        assert cfg.pre_tool_use == ["echo hi"]
+        assert cfg.post_tool_use == []
+        Path(f.name).unlink()
+
+
+class TestHookRunner:
+    def test_no_commands_returns_allow(self):
+        runner = HookRunner(HookConfig())
+        result = runner.run_pre_tool_use("Read", '{"path":"README.md"}')
+        assert not result.denied
+        assert result.messages == []
+
+    def test_exit_zero_captures_stdout(self):
+        runner = HookRunner(HookConfig(pre_tool_use=["printf 'pre ok'"]))
+        result = runner.run_pre_tool_use("Read", '{"path":"README.md"}')
+        assert not result.denied
+        assert result.messages == ["pre ok"]
+
+    def test_exit_two_denies(self):
+        runner = HookRunner(HookConfig(pre_tool_use=["printf 'blocked'; exit 2"]))
+        result = runner.run_pre_tool_use("Bash", '{"command":"pwd"}')
+        assert result.denied
+        assert result.messages == ["blocked"]
+
+    def test_exit_two_without_stdout_uses_default_message(self):
+        runner = HookRunner(HookConfig(pre_tool_use=["exit 2"]))
+        result = runner.run_pre_tool_use("Bash", '{"command":"pwd"}')
+        assert result.denied
+        assert "denied" in result.messages[0]
+        assert "Bash" in result.messages[0]
+
+    def test_other_exit_code_warns_but_allows(self):
+        runner = HookRunner(HookConfig(pre_tool_use=["printf 'oops'; exit 1"]))
+        result = runner.run_pre_tool_use("Edit", '{"file":"lib.py"}')
+        assert not result.denied
+        assert len(result.messages) == 1
+        assert "allowing tool execution to continue" in result.messages[0]
+
+    def test_short_circuit_on_deny(self):
+        runner = HookRunner(HookConfig(pre_tool_use=[
+            "printf 'first ok'",
+            "printf 'deny'; exit 2",
+            "printf 'never reached'",
+        ]))
+        result = runner.run_pre_tool_use("Bash", '{}')
+        assert result.denied
+        assert result.messages == ["first ok", "deny"]
+
+    def test_post_tool_use(self):
+        runner = HookRunner(HookConfig(post_tool_use=["printf 'post ok'"]))
+        result = runner.run_post_tool_use("Read", '{}', "file contents", is_error=False)
+        assert not result.denied
+        assert result.messages == ["post ok"]
+
+    def test_env_vars_passed(self):
+        runner = HookRunner(HookConfig(pre_tool_use=[
+            'printf "%s %s" "$HOOK_EVENT" "$HOOK_TOOL_NAME"'
+        ]))
+        result = runner.run_pre_tool_use("Bash", '{"command":"ls"}')
+        assert not result.denied
+        assert result.messages == ["PreToolUse Bash"]
+
+    def test_stdin_payload(self):
+        runner = HookRunner(HookConfig(pre_tool_use=[
+            """python3 -c "import sys, json; d=json.load(sys.stdin); print(d['tool_name'])" """
+        ]))
+        result = runner.run_pre_tool_use("Grep", '{"pattern":"foo"}')
+        assert not result.denied
+        assert result.messages == ["Grep"]
+
+    def test_multiple_commands_collect_messages(self):
+        runner = HookRunner(HookConfig(pre_tool_use=[
+            "printf 'msg1'",
+            "printf 'msg2'",
+        ]))
+        result = runner.run_pre_tool_use("Read", '{}')
+        assert not result.denied
+        assert result.messages == ["msg1", "msg2"]
+
+    def test_from_settings(self):
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump({"hooks": {"pre_tool_use": ["printf 'from settings'"]}}, f)
+            f.flush()
+            runner = HookRunner.from_settings(f.name)
+        result = runner.run_pre_tool_use("Bash", '{}')
+        assert not result.denied
+        assert result.messages == ["from settings"]
+        Path(f.name).unlink()