docs: add session handover for pre-commit hooks and agent configuration fixes

Author: Terraphim CI

.docs/handover-2025-02-17.md

@@ -0,0 +1,126 @@
+# Session Handover - 2025-02-17
+
+## Progress Summary
+
+### Tasks Completed
+
+1. **Git Pull & Rebase** ✅
+   - Pulled 32 commits from origin/main
+   - Resolved untracked cachebro cache files blocking merge
+
+2. **Pre-commit Hook macOS Compatibility** ✅
+   - **Issue**: Hook used `timeout` command (doesn't exist on macOS)
+   - **Fix**: Added `run_with_timeout()` cross-platform function supporting:
+     - Linux: native `timeout`
+     - macOS: `gtimeout` (Homebrew) or Perl `alarm`
+     - Fallback: run without timeout
+   - **Files Changed**: `.git/hooks/pre-commit`
+
+3. **Claude Configuration Fixes** ✅
+   - **Fixed**: `post_tool_use.sh` hook error (terraphim-agent not in PATH)
+   - **Fixed**: PreToolUse/PostToolUse hooks to prefer release binaries over debug
+   - **Fixed**: MCP Agent Mail token sync across Claude/OpenCode/Codex
+   - **Files Changed**:
+     - `~/.claude/hooks/pre_tool_use.sh`
+     - `~/.claude/hooks/post_tool_use.sh`
+     - `~/.claude/settings.json`
+
+4. **OpenCode Configuration** ✅
+   - **Created**: `~/.config/opencode/CLAUDE.md` with core rules
+
+5. **Codex Configuration** ✅
+   - **Fixed**: Disabled broken notify hook path (pointed to non-existent file)
+   - **Files Changed**: `~/.codex/config.toml`
+
+6. **Terraphim Hooks Skill Update** ✅
+   - **Added**: GitHub release download instructions
+   - **Added**: Binary priority documentation (release > debug)
+   - **Added**: Upgrade instructions and troubleshooting
+   - **Files Changed**: `~/.agents/skills/terraphim-hooks/SKILL.md`
+
+---
+
+## Technical Context
+
+```bash
+# Current branch
+main
+
+# Recent commits
+3d40642e docs: update PostToolUse hook format to new array syntax with matchers
+13434a8c docs(blog): publish zvec vs Terraphim comparison article
+36c2d5a7 docs(blog): publish multi-haystack roles announcement
+2d97e924 feat(templates): add GrepApp haystack to FrontEnd and Python Engineer roles
+d295bb50 fix(onboard): correct Rust Engineer v2 implementation
+```
+
+---
+
+## Configuration Changes
+
+### Claude Hooks Binary Priority
+
+Hooks now search for terraphim-agent in this order:
+
+1. `~/.cargo/bin/terraphim-agent` (GitHub release) ← **PREFERRED**
+2. `~/projects/terraphim/terraphim-ai/target/release/terraphim-agent`
+3. `~/projects/terraphim/terraphim-ai/target/debug/terraphim-agent` (fallback)
+4. `terraphim-agent` (PATH)
+
+### MCP Agent Mail Token (Synced)
+
+All three tools now use the same token:
+- Claude: `bca2fa4fac...50feee`
+- OpenCode: `bca2fa4fac...50feee`
+- Codex: `bca2fa4fac...50feee`
+
+---
+
+## Next Steps
+
+### 1. Install terraphim-agent Release Binary
+
+```bash
+# macOS ARM64 (Apple Silicon)
+curl -L "https://github.com/terraphim/terraphim-ai/releases/latest/download/terraphim-agent-aarch64-apple-darwin" \
+  -o ~/.cargo/bin/terraphim-agent
+chmod +x ~/.cargo/bin/terraphim-agent
+
+# Verify installation
+terraphim-agent --version
+```
+
+### 2. Verify Hooks Work
+
+```bash
+# Test PreToolUse hook
+echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ~/.claude/hooks/pre_tool_use.sh
+
+# Should output without errors (may transform command if KG configured)
+```
+
+### 3. Optional: Create Codex Notify Wrapper
+
+The notify hook in `~/.codex/config.toml` is currently disabled. To enable:
+- Create `/Users/alex/projects/terraphim/terraphim-skills/mcp_agent_mail/.codex/hooks/notify_wrapper.sh`
+- Or update path to existing notification script
+
+---
+
+## Blocked Items
+
+None - all configuration issues resolved. Ready to resume normal development work.
+
+---
+
+## Key Files Modified (Local Config)
+
+| File | Change |
+|------|--------|
+| `.git/hooks/pre-commit` | Added cross-platform timeout support |
+| `~/.claude/hooks/pre_tool_use.sh` | Prefer release binary, fail-open |
+| `~/.claude/hooks/post_tool_use.sh` | Prefer release binary, fail-open |
+| `~/.claude/settings.json` | Synced MCP Agent Mail token |
+| `~/.config/opencode/CLAUDE.md` | Created with core rules |
+| `~/.codex/config.toml` | Disabled broken notify hook |
+| `~/.agents/skills/terraphim-hooks/SKILL.md` | Added release binary instructions |