refactor(hooks): introduce typed HookDecision classes

Add hook_decision.py with HookEvent, PreToolUseOutcome, PreToolUseDecision,
and PostToolUseContext. Each class owns its own to_payload() serialization so
callers have no branches over event type. hooks_cmd.py is untouched; existing
tests remain green.

Author: TTTPOB

jupyter_jcli/hook_decision.py

@@ -0,0 +1,74 @@
+"""Typed hook decisions — each class owns its Claude Code output schema.
+
+PreToolUse and PostToolUse have fundamentally different JSON shapes
+and semantics. PreToolUse is a permission gate (allow/deny/ask).
+PostToolUse can only inject context — the tool already ran, so there
+is no meaningful way to "deny" it. Each valid (event, outcome) pair
+is modelled as its own dataclass so the emitter has no branches.
+
+See https://code.claude.com/docs/en/hooks for the wire schema.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol
+
+
+class HookEvent(str, Enum):
+    """Claude Code hook event names — single source of truth for the
+    wire strings that appear in payload's hookEventName field."""
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+
+
+class PreToolUseOutcome(str, Enum):
+    """Valid values for PreToolUse permissionDecision."""
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+
+
+class HookDecision(Protocol):
+    """Anything that serializes to a Claude Code hook JSON payload."""
+    def to_payload(self) -> dict: ...
+
+
+@dataclass(frozen=True)
+class PreToolUseDecision:
+    """Permission gate emitted from a PreToolUse hook.
+
+    - ALLOW/ASK: reason shown to the user
+    - DENY:      reason shown to Claude (fed into its context)
+    """
+    outcome: PreToolUseOutcome
+    reason: str
+
+    def to_payload(self) -> dict:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": HookEvent.PRE_TOOL_USE.value,
+                "permissionDecision": self.outcome.value,
+                "permissionDecisionReason": self.reason,
+            }
+        }
+
+
+@dataclass(frozen=True)
+class PostToolUseContext:
+    """Non-blocking context injection from a PostToolUse hook.
+
+    The tool already ran — we can only tell Claude what happened.
+    Used for both "paired file auto-synced" and "paired file drifted,
+    someone else may have edited it" notifications.
+    """
+    context: str
+
+    def to_payload(self) -> dict:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": HookEvent.POST_TOOL_USE.value,
+                "additionalContext": self.context,
+            }
+        }

tests/test_hook_decision.py

@@ -0,0 +1,96 @@
+"""Unit tests for jupyter_jcli.hook_decision typed decision classes."""
+
+import pytest
+
+from jupyter_jcli.hook_decision import (
+    HookEvent,
+    PostToolUseContext,
+    PreToolUseDecision,
+    PreToolUseOutcome,
+)
+
+
+class TestHookEvent:
+    def test_pre_tool_use_value(self):
+        assert HookEvent.PRE_TOOL_USE == "PreToolUse"
+        assert isinstance(HookEvent.PRE_TOOL_USE, str)
+
+    def test_post_tool_use_value(self):
+        assert HookEvent.POST_TOOL_USE == "PostToolUse"
+        assert isinstance(HookEvent.POST_TOOL_USE, str)
+
+    def test_invalid_event_raises(self):
+        with pytest.raises(ValueError):
+            HookEvent("bogus")
+
+
+class TestPreToolUseOutcome:
+    def test_allow(self):
+        assert PreToolUseOutcome.ALLOW == "allow"
+        assert isinstance(PreToolUseOutcome.ALLOW, str)
+
+    def test_deny(self):
+        assert PreToolUseOutcome.DENY == "deny"
+
+    def test_ask(self):
+        assert PreToolUseOutcome.ASK == "ask"
+
+    def test_invalid_outcome_raises(self):
+        with pytest.raises(ValueError):
+            PreToolUseOutcome("bogus")
+
+
+class TestPreToolUseDecision:
+    def test_deny_payload(self):
+        d = PreToolUseDecision(PreToolUseOutcome.DENY, "you shall not pass")
+        p = d.to_payload()
+        assert p == {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "you shall not pass",
+            }
+        }
+
+    def test_allow_payload(self):
+        d = PreToolUseDecision(PreToolUseOutcome.ALLOW, "go ahead")
+        p = d.to_payload()
+        assert p["hookSpecificOutput"]["permissionDecision"] == "allow"
+        assert p["hookSpecificOutput"]["permissionDecisionReason"] == "go ahead"
+        assert "additionalContext" not in p["hookSpecificOutput"]
+
+    def test_ask_payload(self):
+        d = PreToolUseDecision(PreToolUseOutcome.ASK, "are you sure?")
+        p = d.to_payload()
+        assert p["hookSpecificOutput"]["permissionDecision"] == "ask"
+        assert p["hookSpecificOutput"]["hookEventName"] == "PreToolUse"
+
+    def test_no_additional_context_in_pre(self):
+        d = PreToolUseDecision(PreToolUseOutcome.DENY, "reason")
+        p = d.to_payload()
+        assert "additionalContext" not in p["hookSpecificOutput"]
+        assert "decision" not in p
+
+
+class TestPostToolUseContext:
+    def test_payload_shape(self):
+        c = PostToolUseContext("paired notebook drifted, run j-cli convert")
+        p = c.to_payload()
+        assert p == {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "paired notebook drifted, run j-cli convert",
+            }
+        }
+
+    def test_no_permission_decision_in_post(self):
+        c = PostToolUseContext("some context")
+        p = c.to_payload()
+        assert "permissionDecision" not in p["hookSpecificOutput"]
+        assert "permissionDecisionReason" not in p["hookSpecificOutput"]
+        assert "decision" not in p
+
+    def test_auto_synced_context(self):
+        c = PostToolUseContext("Auto-synced foo.py to bar.ipynb. Pair is now in sync.")
+        p = c.to_payload()
+        assert "Auto-synced" in p["hookSpecificOutput"]["additionalContext"]