feat(hooks): integrate UserPromptSubmit hook

- hooks.json: Switch to signal-detecting user_prompt.py handler
- config_loader.py: Add user_prompt_enabled config with env var
- models.py: Update exports for capture decision types
- PROGRESS.md: Document Phase 3 completion (6/6 tasks)

Author: zircote

docs/spec/active/2025-12-19-hook-based-memory-capture/PROGRESS.md

@@ -4,7 +4,7 @@ format_version: "1.0.0"
 project_id: SPEC-2025-12-19-001
 project_name: "Hook-Based Memory Capture"
 project_status: in-progress
-current_phase: 3
+current_phase: 4
 implementation_started: 2025-12-19T00:00:00Z
 last_session: 2025-12-19T00:00:00Z
 last_updated: 2025-12-19T00:00:00Z
@@ -36,12 +36,12 @@ This document tracks implementation progress against the spec plan.
 | 2.3 | Implement Budget Calculator | done | 2025-12-19 | 2025-12-19 | Integrated into ContextBuilder with adaptive tiers |
 | 2.4 | Create SessionStart Hook Handler | done | 2025-12-19 | 2025-12-19 | Created `hooks/session_start_handler.py` |
 | 2.5 | Register SessionStart Hook | done | 2025-12-19 | 2025-12-19 | Created `hooks/session_start.py` wrapper, updated hooks.json |
-| 3.1 | Implement SignalDetector | pending | | | Pattern matching for signals |
-| 3.2 | Implement Novelty Checker | pending | | | Duplicate detection |
-| 3.3 | Implement CaptureDecider | pending | | | Decision logic |
-| 3.4 | Create UserPromptSubmit Hook Handler | pending | | | hooks/user_prompt.py |
-| 3.5 | Format Capture Suggestions | pending | | | XML suggestion format |
-| 3.6 | Register UserPromptSubmit Hook | pending | | | Update hooks.json |
+| 3.1 | Implement SignalDetector | done | 2025-12-19 | 2025-12-19 | Created `hooks/signal_detector.py` with pattern matching |
+| 3.2 | Implement Novelty Checker | done | 2025-12-19 | 2025-12-19 | Created `hooks/novelty_checker.py` with semantic similarity |
+| 3.3 | Implement CaptureDecider | done | 2025-12-19 | 2025-12-19 | Created `hooks/capture_decider.py` with threshold-based decision logic |
+| 3.4 | Create UserPromptSubmit Hook Handler | done | 2025-12-19 | 2025-12-19 | Created `hooks/user_prompt_handler.py` |
+| 3.5 | Format Capture Suggestions | done | 2025-12-19 | 2025-12-19 | XML formatter in handler via XMLBuilder |
+| 3.6 | Register UserPromptSubmit Hook | done | 2025-12-19 | 2025-12-19 | Updated hooks.json, created wrapper |
 | 4.1 | Implement Session Analyzer | pending | | | Transcript analysis |
 | 4.2 | Detect Uncaptured Memories | pending | | | Filter already-captured |
 | 4.3 | Enhance Stop Hook Handler | pending | | | Update hooks/stop.py |
@@ -63,7 +63,7 @@ This document tracks implementation progress against the spec plan.
 |-------|------|----------|--------|
 | 1 | Core Hook Infrastructure | 100% | done |
 | 2 | SessionStart Context Injection | 100% | done |
-| 3 | Capture Signal Detection | 0% | pending |
+| 3 | Capture Signal Detection | 100% | done |
 | 4 | Stop Hook Enhancement | 0% | pending |
 | 5 | Testing & Documentation | 0% | pending |
 
@@ -128,3 +128,26 @@ This document tracks implementation progress against the spec plan.
   - `mypy` - No issues found in 8 source files
   - `pytest` - 910 tests passed
 - Ready for Phase 3: Capture Signal Detection
+
+### 2025-12-19 - Phase 3 Complete
+- **Phase 3 completed**: All 6 tasks done
+- Created signal detection and capture decision pipeline:
+  - `signal_detector.py` - Pattern-based detection for decisions, learnings, blockers
+  - `novelty_checker.py` - Semantic similarity checking to avoid duplicates
+  - `capture_decider.py` - Threshold-based decision logic (AUTO/SUGGEST/SKIP)
+- Created `src/git_notes_memory/hooks/user_prompt_handler.py`:
+  - Full UserPromptSubmit handler with signal detection pipeline
+  - AUTO capture for high-confidence signals (≥0.95)
+  - SUGGEST for medium-confidence signals (0.7-0.95)
+  - XML-formatted suggestions for additionalContext injection
+  - Non-blocking error handling (exit 0 on all paths)
+- Created `hooks/user_prompt.py` wrapper script
+- Updated `hooks/hooks.json`:
+  - Changed UserPromptSubmit to use new signal-detecting handler
+  - Hook disabled by default (opt-in via HOOK_USER_PROMPT_ENABLED)
+- Added `user_prompt_enabled` to HookConfig with env var support
+- All quality gates passed:
+  - `ruff check` - All checks passed
+  - `mypy` - No issues found in 11 source files
+  - `pytest` - 910 tests passed
+- Ready for Phase 4: Stop Hook Enhancement

hooks/hooks.json

@@ -8,8 +8,8 @@
     },
     {
       "event": "UserPromptSubmit",
-      "script": "userpromptsubmit.py",
-      "description": "Optional: Captures significant prompts as memories when marker is present",
+      "script": "user_prompt.py",
+      "description": "Detects memorable content (decisions, learnings, blockers) and suggests capture",
       "enabled": false
     },
     {

src/git_notes_memory/hooks/__init__.py

@@ -43,8 +43,12 @@
     "TokenBudget",
     # Signal Detection
     "SignalDetector",
+    "SIGNAL_PATTERNS",
     "CaptureSignal",
     "SignalType",
+    # Novelty Checking
+    "NoveltyChecker",
+    "NoveltyResult",
     # Capture Decision
     "CaptureDecider",
     "CaptureDecision",
@@ -90,6 +94,10 @@ def __getattr__(name: str) -> object:
         from git_notes_memory.hooks.signal_detector import SignalDetector
 
         return SignalDetector
+    if name == "SIGNAL_PATTERNS":
+        from git_notes_memory.hooks.signal_detector import SIGNAL_PATTERNS
+
+        return SIGNAL_PATTERNS
     if name == "CaptureSignal":
         from git_notes_memory.hooks.models import CaptureSignal
 
@@ -99,6 +107,16 @@ def __getattr__(name: str) -> object:
 
         return SignalType
 
+    # Novelty Checking
+    if name == "NoveltyChecker":
+        from git_notes_memory.hooks.novelty_checker import NoveltyChecker
+
+        return NoveltyChecker
+    if name == "NoveltyResult":
+        from git_notes_memory.hooks.models import NoveltyResult
+
+        return NoveltyResult
+
     # Capture Decision
     if name == "CaptureDecider":
         from git_notes_memory.hooks.capture_decider import CaptureDecider

src/git_notes_memory/hooks/config_loader.py

@@ -15,6 +15,7 @@
     HOOK_CAPTURE_DETECTION_MIN_CONFIDENCE: Minimum confidence for suggestions
     HOOK_CAPTURE_DETECTION_AUTO_THRESHOLD: Confidence for auto-capture
     HOOK_CAPTURE_DETECTION_NOVELTY_THRESHOLD: Novelty score threshold
+    HOOK_USER_PROMPT_ENABLED: Enable UserPromptSubmit hook
     HOOK_STOP_ENABLED: Enable Stop hook
     HOOK_STOP_PROMPT_UNCAPTURED: Prompt for uncaptured content
     HOOK_TIMEOUT: Default hook timeout in seconds
@@ -90,6 +91,9 @@ class HookConfig:
     stop_prompt_uncaptured: bool = True
     stop_sync_index: bool = True
 
+    # UserPromptSubmit hook settings
+    user_prompt_enabled: bool = False  # Uses capture_detection_enabled by default
+
     # Performance settings
     timeout: int = 30
     debug: bool = False
@@ -261,6 +265,12 @@ def load_hook_config(env: dict[str, str] | None = None) -> HookConfig:
             defaults.capture_detection_novelty_threshold,
         )
 
+    # UserPromptSubmit hook settings
+    if "HOOK_USER_PROMPT_ENABLED" in env:
+        kwargs["user_prompt_enabled"] = _parse_bool(
+            env["HOOK_USER_PROMPT_ENABLED"]
+        )
+
     # Stop hook settings
     if "HOOK_STOP_ENABLED" in env:
         kwargs["stop_enabled"] = _parse_bool(env["HOOK_STOP_ENABLED"])

src/git_notes_memory/hooks/models.py

@@ -22,6 +22,7 @@
 __all__ = [
     "SignalType",
     "CaptureSignal",
+    "NoveltyResult",
     "CaptureAction",
     "CaptureDecision",
     "SuggestedCapture",
@@ -101,6 +102,32 @@ def __post_init__(self) -> None:
             raise ValueError(msg)
 
 
+@dataclass(frozen=True)
+class NoveltyResult:
+    """Result of novelty checking for a capture signal.
+
+    Indicates whether detected content is novel (should be captured)
+    or a duplicate of existing memories.
+
+    Attributes:
+        novelty_score: Score from 0.0 (duplicate) to 1.0 (completely new).
+        is_novel: Whether the content passes the novelty threshold.
+        similar_memory_ids: IDs of similar existing memories.
+        highest_similarity: Highest similarity score found.
+    """
+
+    novelty_score: float
+    is_novel: bool
+    similar_memory_ids: list[str] = field(default_factory=list)
+    highest_similarity: float = 0.0
+
+    def __post_init__(self) -> None:
+        """Validate novelty score is in valid range."""
+        if not 0.0 <= self.novelty_score <= 1.0:
+            msg = f"Novelty score must be between 0.0 and 1.0, got {self.novelty_score}"
+            raise ValueError(msg)
+
+
 class CaptureAction(Enum):
     """Actions the capture decider can take.