test(hooks): add comprehensive hook test suite (Phase 5)

Add 132 hook-specific tests covering:
- Unit tests for hook services (51 tests)
- Unit tests for hook handlers (43 tests)
- Integration tests for end-to-end flows (21 tests)
- Performance tests with timing benchmarks (17 tests)

Update documentation:
- README.md: hooks integration section and env vars
- USER_GUIDE.md: comprehensive hooks documentation (~150 lines)
- CHANGELOG.md: hooks feature in [Unreleased] section

Bug fix:
- session_start_handler.py: add JSON output on error paths

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: zircote

CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+#### Claude Code Hooks Integration
+- **SessionStart Hook**: Automatic context injection at session start
+  - Project and spec detection from git repo, pyproject.toml, package.json
+  - Adaptive token budget calculation (adaptive/fixed/full/minimal modes)
+  - Working memory injection: pending actions, recent decisions, active blockers
+  - Semantic context: relevant learnings and patterns for the project
+  - XML-formatted output for Claude Code additionalContext
+
+- **UserPromptSubmit Hook**: Capture signal detection (opt-in)
+  - Pattern-based detection for decisions, learnings, blockers, progress
+  - Confidence scoring with configurable thresholds
+  - AUTO capture for high-confidence signals (≥95%)
+  - SUGGEST action for medium-confidence signals (70-95%)
+  - Novelty checking to avoid duplicate captures
+
+- **Stop Hook**: Session-end processing
+  - Session transcript analysis for uncaptured memorable content
+  - Prompts for uncaptured decisions, learnings, blockers
+  - Automatic search index synchronization
+
+#### Hook Infrastructure
+- `HookConfig` dataclass with environment variable configuration
+- `XMLBuilder` for structured context serialization
+- `ContextBuilder` for memory context assembly
+- `ProjectDetector` for automatic project/spec identification
+- `SignalDetector` for capture-worthy content detection
+- `NoveltyChecker` for semantic similarity against existing memories
+- `CaptureDecider` for threshold-based capture decisions
+- `SessionAnalyzer` for transcript parsing and analysis
+
+#### Hook Configuration
+- Environment variables: HOOK_ENABLED, HOOK_SESSION_START_ENABLED, HOOK_USER_PROMPT_ENABLED, HOOK_STOP_ENABLED
+- Budget configuration: HOOK_SESSION_START_BUDGET_MODE, HOOK_SESSION_START_FIXED_BUDGET, HOOK_SESSION_START_MAX_BUDGET
+- Detection thresholds: HOOK_CAPTURE_DETECTION_MIN_CONFIDENCE, HOOK_CAPTURE_DETECTION_AUTO_THRESHOLD, HOOK_CAPTURE_DETECTION_NOVELTY_THRESHOLD
+- Debug mode: HOOK_DEBUG for stderr logging
+
+### Testing
+- 132 hook-specific tests (51 services + 43 handlers + 21 integration + 17 performance)
+- Performance benchmarks: <5ms signal detection, <50ms single prompt, <10ms full pipeline
+
+### Documentation
+- Hooks Integration section in User Guide
+- Configuration reference for all hook environment variables
+- Troubleshooting guide for common hook issues
+
 ## [0.1.0] - 2024-12-19
 
 ### Added

README.md

@@ -58,6 +58,16 @@ When used as a Claude Code plugin, the following commands are available:
 - `/memory verify` - Check index consistency
 - `/memory gc` - Garbage collect old memories
 
+### Hooks Integration
+
+The plugin includes hooks that integrate with Claude Code's hook system for automatic memory context:
+
+- **SessionStart**: Injects relevant project memories at session start
+- **UserPromptSubmit**: Detects capture-worthy content in user prompts (opt-in)
+- **Stop**: Prompts for uncaptured content and syncs the search index
+
+See [User Guide](docs/USER_GUIDE.md#hooks-integration) for configuration options.
+
 ## Development
 
 ```bash
@@ -84,7 +94,11 @@ Environment variables:
 | `MEMORY_PLUGIN_DATA_DIR` | Data directory path | `~/.local/share/memory-plugin/` |
 | `MEMORY_PLUGIN_GIT_NAMESPACE` | Git notes namespace | `refs/notes/mem` |
 | `MEMORY_PLUGIN_EMBEDDING_MODEL` | Embedding model name | `all-MiniLM-L6-v2` |
-| `MEMORY_PLUGIN_AUTO_CAPTURE` | Enable auto-capture hook | `false` |
+| `HOOK_ENABLED` | Master switch for hooks | `true` |
+| `HOOK_SESSION_START_ENABLED` | Enable SessionStart context injection | `true` |
+| `HOOK_USER_PROMPT_ENABLED` | Enable signal detection in prompts | `false` |
+| `HOOK_STOP_ENABLED` | Enable Stop hook processing | `true` |
+| `HOOK_DEBUG` | Enable debug logging to stderr | `false` |
 
 ## Requirements
 

docs/USER_GUIDE.md

@@ -432,6 +432,145 @@ git fetch origin refs/notes/mem:refs/notes/mem
 
 ---
 
+## Hooks Integration
+
+The memory plugin includes hooks that integrate with Claude Code's hook system for automatic memory context injection and capture assistance.
+
+### Overview
+
+Three hooks are available:
+
+| Hook | Event | Purpose | Default |
+|------|-------|---------|---------|
+| SessionStart | Session begins | Inject project memories | Enabled |
+| UserPromptSubmit | User sends prompt | Detect capture signals | Disabled |
+| Stop | Session ends | Prompt for uncaptured content, sync index | Enabled |
+
+### SessionStart Hook
+
+Automatically injects relevant memories at the start of each Claude Code session.
+
+**What it does:**
+1. Detects the current project (from git repo, package.json, pyproject.toml)
+2. Identifies the active spec (from CLAUDE.md or docs/spec/active/)
+3. Builds context within a token budget
+4. Injects XML-formatted memory context
+
+**Context includes:**
+- Working memory: pending actions, recent decisions, active blockers
+- Semantic context: learnings and patterns relevant to the project
+- Available commands: quick reference for memory operations
+
+**Configuration:**
+
+```bash
+# Disable SessionStart hook
+export HOOK_SESSION_START_ENABLED=false
+
+# Budget modes: adaptive (default), fixed, full, minimal
+export HOOK_SESSION_START_BUDGET_MODE=adaptive
+
+# Fixed budget (when mode=fixed)
+export HOOK_SESSION_START_FIXED_BUDGET=1000
+
+# Maximum budget cap
+export HOOK_SESSION_START_MAX_BUDGET=3000
+```
+
+### UserPromptSubmit Hook
+
+Analyzes user prompts for capture-worthy content and suggests or auto-captures memories.
+
+**What it detects:**
+- **Decisions**: "I decided to use...", "we're going with..."
+- **Learnings**: "I learned that...", "TIL:", "turns out..."
+- **Blockers**: "blocked by...", "stuck on...", "can't because..."
+- **Progress**: "completed...", "finished...", "done with..."
+
+**Capture actions:**
+- **AUTO**: High-confidence signals (≥95%) are captured automatically
+- **SUGGEST**: Medium-confidence signals (70-95%) show suggestions
+- **SKIP**: Low-confidence or duplicate content is ignored
+
+**Configuration:**
+
+```bash
+# Enable signal detection (disabled by default)
+export HOOK_USER_PROMPT_ENABLED=true
+
+# Minimum confidence for suggestions (0.0-1.0)
+export HOOK_CAPTURE_DETECTION_MIN_CONFIDENCE=0.7
+
+# Threshold for auto-capture (0.0-1.0)
+export HOOK_CAPTURE_DETECTION_AUTO_THRESHOLD=0.95
+
+# Novelty threshold (how different from existing memories)
+export HOOK_CAPTURE_DETECTION_NOVELTY_THRESHOLD=0.3
+```
+
+### Stop Hook
+
+Performs session-end cleanup and memory assistance.
+
+**What it does:**
+1. Analyzes session transcript for uncaptured memorable content
+2. Prompts user with suggestions if valuable content found
+3. Synchronizes the memory search index
+
+**Configuration:**
+
+```bash
+# Disable Stop hook
+export HOOK_STOP_ENABLED=false
+
+# Disable uncaptured content prompts
+export HOOK_STOP_PROMPT_UNCAPTURED=false
+
+# Disable index sync on session end
+export HOOK_STOP_SYNC_INDEX=false
+```
+
+### Global Hook Configuration
+
+```bash
+# Master switch - disable all hooks
+export HOOK_ENABLED=false
+
+# Enable debug logging to stderr
+export HOOK_DEBUG=true
+
+# Hook timeout in seconds (default: 30)
+export HOOK_TIMEOUT=30
+```
+
+### Hook Installation
+
+The hooks are installed automatically when you configure the plugin in Claude Code. The hook scripts are in the `hooks/` directory:
+
+- `hooks/session_start.py` - SessionStart event handler
+- `hooks/user_prompt.py` - UserPromptSubmit event handler
+- `hooks/stop.py` - Stop event handler
+- `hooks/hooks.json` - Hook registration configuration
+
+### Troubleshooting Hooks
+
+**Hook not triggering:**
+1. Check if hooks are enabled: `echo $HOOK_ENABLED`
+2. Verify hook registration in `hooks/hooks.json`
+3. Enable debug mode: `export HOOK_DEBUG=true`
+
+**Slow session start:**
+1. Reduce budget: `export HOOK_SESSION_START_BUDGET_MODE=minimal`
+2. Check index size with `/memory status`
+3. Run incremental reindex: `/memory sync`
+
+**Too many capture suggestions:**
+1. Increase confidence threshold: `export HOOK_CAPTURE_DETECTION_MIN_CONFIDENCE=0.8`
+2. Disable auto-capture: `export HOOK_CAPTURE_DETECTION_AUTO_THRESHOLD=1.0`
+3. Disable hook entirely: `export HOOK_USER_PROMPT_ENABLED=false`
+
+---
+
 ## Next Steps
 
 - See [Developer Guide](DEVELOPER_GUIDE.md) for API reference

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

@@ -3,7 +3,7 @@ document_type: progress
 format_version: "1.0.0"
 project_id: SPEC-2025-12-19-001
 project_name: "Hook-Based Memory Capture"
-project_status: in-progress
+project_status: complete
 current_phase: 5
 implementation_started: 2025-12-19T00:00:00Z
 last_session: 2025-12-19T00:00:00Z
@@ -47,13 +47,13 @@ This document tracks implementation progress against the spec plan.
 | 4.3 | Enhance Stop Hook Handler | done | 2025-12-19 | 2025-12-19 | Created `hooks/stop_handler.py` |
 | 4.4 | Implement Capture Prompt | done | 2025-12-19 | 2025-12-19 | XML formatting in stop_handler |
 | 4.5 | Index Synchronization | done | 2025-12-19 | 2025-12-19 | SyncService integration in stop_handler |
-| 5.1 | Unit Tests - Hook Services | pending | | | XMLBuilder, ContextBuilder, etc. |
-| 5.2 | Unit Tests - Hook Handlers | pending | | | Hook script tests |
-| 5.3 | Integration Tests | pending | | | End-to-end flows |
-| 5.4 | Performance Tests | pending | | | Timing benchmarks |
-| 5.5 | Hook Script Testing | pending | | | Manual testing with fixtures |
-| 5.6 | Documentation Updates | pending | | | README, CLAUDE.md |
-| 5.7 | Update CHANGELOG | pending | | | Release notes |
+| 5.1 | Unit Tests - Hook Services | done | 2025-12-19 | 2025-12-19 | 51 tests covering all hook services |
+| 5.2 | Unit Tests - Hook Handlers | done | 2025-12-19 | 2025-12-19 | 43 tests covering all handlers |
+| 5.3 | Integration Tests | done | 2025-12-19 | 2025-12-19 | 21 tests covering end-to-end flows |
+| 5.4 | Performance Tests | done | 2025-12-19 | 2025-12-19 | 17 tests covering timing requirements |
+| 5.5 | Hook Script Testing | done | 2025-12-19 | 2025-12-19 | Manual testing complete, bug fix applied |
+| 5.6 | Documentation Updates | done | 2025-12-19 | 2025-12-19 | README, USER_GUIDE updated |
+| 5.7 | Update CHANGELOG | done | 2025-12-19 | 2025-12-19 | Added hooks feature to [Unreleased] |
 
 ---
 
@@ -65,7 +65,7 @@ This document tracks implementation progress against the spec plan.
 | 2 | SessionStart Context Injection | 100% | done |
 | 3 | Capture Signal Detection | 100% | done |
 | 4 | Stop Hook Enhancement | 100% | done |
-| 5 | Testing & Documentation | 0% | pending |
+| 5 | Testing & Documentation | 100% | done |
 
 ---
 
@@ -74,6 +74,8 @@ This document tracks implementation progress against the spec plan.
 | Date | Type | Task ID | Description | Resolution |
 |------|------|---------|-------------|------------|
 | 2025-12-19 | refinement | 2.4 | Handler renamed to `session_start_handler.py` | Clarifies two-layer architecture (wrapper script vs handler module) |
+| 2025-12-19 | bugfix | 1.3 | Budget tier allocations exceeded total when commands added | Fixed tiers: total ≥ working_memory + semantic_context + commands(100) |
+| 2025-12-19 | bugfix | 2.4 | session_start_handler.py missing JSON output on error paths | Added `print(json.dumps({"continue": True}))` to exception handlers |
 
 ---
 
@@ -175,3 +177,58 @@ This document tracks implementation progress against the spec plan.
   - `mypy` - No issues found in 13 source files
   - `pytest` - 910 tests passed
 - Ready for Phase 5: Testing & Documentation
+
+### 2025-12-19 - Task 5.4 Complete (Performance Tests)
+- **Task 5.4 completed**: 17 performance tests added
+- Created `tests/test_hooks_performance.py`:
+  - Signal detection throughput: <5ms per prompt (parametrized 10/50/100 iterations)
+  - Single prompt latency: <50ms per detection
+  - Long prompt handling: <100ms for 5000 char prompts
+  - XML generation performance: <0.1ms creation, <5ms for 100 elements, <2ms serialization
+  - Config loading: <1ms per load
+  - Project detection: <10ms per detection
+  - Capture decision: <1ms per decision (with novelty checks disabled)
+  - Session transcript analysis: <50ms for 100-message transcripts
+  - Full pipeline timing: <10ms per prompt through detection→decision pipeline
+  - Memory usage tests for detector and XML builder reuse
+- Fixed test compatibility:
+  - Used `check_novelty_enabled=False` to avoid database calls in performance tests
+  - Updated budget tier test values to match current implementation (300/100)
+- All 131 tests pass (51+43+20+17)
+- Quality gates: `ruff check` ✓, `mypy` ✓, `pytest` 131 passed ✓
+
+### 2025-12-19 - Task 5.5 Complete (Hook Script Testing)
+- **Task 5.5 completed**: Manual testing of all hook scripts
+- **Bug found and fixed**: `session_start_handler.py` error paths didn't output JSON
+  - Root cause: Exception handlers logged errors but didn't write to stdout
+  - Fix: Added `print(json.dumps({"continue": True}))` after each logger call
+  - This ensures hook contract is satisfied even on errors
+- Manual test results:
+  - `session_start.py`: Outputs valid JSON on all paths (empty input, invalid JSON, valid input)
+  - `user_prompt.py`: Signal detection working (detected decision signals)
+  - `stop.py`: Outputs sync stats and handles empty input gracefully
+- Edge cases verified:
+  - Empty stdin → `{"continue": true}`
+  - Invalid JSON → `{"continue": true}`
+  - `HOOK_ENABLED=false` → `{"continue": true}` (early exit)
+  - Valid input with signals → proper JSON with additionalContext
+- All 132 hook tests pass (51+43+21+17)
+- Quality gates: `ruff check` ✓, `mypy` ✓, `pytest` 132 passed ✓
+
+### 2025-12-19 - Phase 5 Complete (All Tasks Done)
+- **Task 5.6 completed**: Documentation Updates
+  - Updated README.md with hooks integration section
+  - Added hook environment variables to configuration table
+  - Updated USER_GUIDE.md with comprehensive hooks documentation (~150 lines)
+    - Overview table of three hooks with events, purposes, defaults
+    - Detailed configuration for SessionStart, UserPromptSubmit, Stop hooks
+    - Global hook configuration section
+    - Troubleshooting section for common issues
+- **Task 5.7 completed**: CHANGELOG Updates
+  - Added hooks feature to [Unreleased] section
+  - Documented all three hooks with feature details
+  - Listed new hook infrastructure components
+  - Documented all configuration environment variables
+  - Added testing metrics (132 tests, performance benchmarks)
+- **Project Status**: All 27 tasks across 5 phases complete
+- Quality gates: `ruff check` ✓, `mypy` ✓

src/git_notes_memory/hooks/config_loader.py

@@ -99,13 +99,14 @@ class HookConfig:
     debug: bool = False
 
     # Budget tier thresholds (for adaptive mode)
+    # Note: total must >= working_memory + semantic_context + commands (default 100)
     budget_tiers: tuple[tuple[str, int, int, int], ...] = field(
         default=(
             # (complexity, total_budget, working_memory, semantic_context)
-            ("simple", 500, 350, 150),
-            ("medium", 1000, 600, 400),
-            ("complex", 2000, 1000, 1000),
-            ("full", 3000, 1500, 1500),
+            ("simple", 500, 300, 100),  # 300+100+100=500
+            ("medium", 1000, 500, 300),  # 500+300+100=900 (margin for commands)
+            ("complex", 2000, 900, 900),  # 900+900+100=1900 (margin)
+            ("full", 3000, 1400, 1400),  # 1400+1400+100=2900 (margin)
         )
     )
 

src/git_notes_memory/hooks/session_start_handler.py

@@ -197,8 +197,10 @@ def main() -> None:
 
     except json.JSONDecodeError as e:
         logger.error("Failed to parse hook input: %s", e)
+        print(json.dumps({"continue": True}))
     except Exception as e:
         logger.exception("SessionStart hook error: %s", e)
+        print(json.dumps({"continue": True}))
     finally:
         _cancel_timeout()