Refactor hooks codebase: reduce complexity and improve maintainability (#204)

* refactor: Clean up hook-response and new-hook files

- Removed 'PreCompact' hook type and associated logic from hook-response.ts for improved type safety.
- Deleted extensive architecture comments in new-hook.ts to streamline code readability.
- Simplified debug logging in new-hook.ts to reduce verbosity.
- Enhanced ensureWorkerRunning function in worker-utils.ts with a final health check before throwing errors.
- Added a new documentation file outlining the hooks cleanup process and future improvements.

* Refactor cleanup and user message hooks

- Updated cleanup-hook.js to improve error handling and remove unnecessary input checks.
- Simplified user-message-hook.js by removing time-sensitive announcements and streamlining output.
- Enhanced logging functionality in both hooks for better debugging and clarity.

* Refactor error handling in hooks to use centralized error handler

- Introduced `handleWorkerError` function in `src/shared/hook-error-handler.ts` to manage worker-related errors.
- Updated `context-hook.ts`, `new-hook.ts`, `save-hook.ts`, and `summary-hook.ts` to utilize the new error handler, simplifying error management and improving code readability.
- Removed repetitive error handling logic from individual hooks, ensuring consistent user-friendly messages for connection issues.

* Refactor user-message and summary hooks to utilize shared transcript parser; introduce hook exit codes

- Moved user message extraction logic to a new shared module `transcript-parser.ts` for better code reuse.
- Updated `summary-hook.ts` to use the new `extractLastMessage` function for retrieving user and assistant messages.
- Replaced direct exit code usage in `user-message-hook.ts` with constants from `hook-constants.ts` for improved readability and maintainability.
- Added `HOOK_EXIT_CODES` to `hook-constants.ts` to standardize exit codes across hooks.

* Refactor hook input interfaces to enforce required fields

- Updated `SessionStartInput`, `UserPromptSubmitInput`, `PostToolUseInput`, and `StopInput` interfaces to require `session_id`, `transcript_path`, and `cwd` fields, ensuring better type safety and clarity in hook inputs.
- Removed optional index signatures from these interfaces to prevent unintended properties and improve code maintainability.
- Adjusted related hook implementations to align with the new interface definitions.

* Refactor save-hook to remove tool skipping logic; enhance summary-hook to handle spinner stopping with error logging; update SessionRoutes to load skip tools from settings; add CLAUDE_MEM_SKIP_TOOLS to SettingsDefaultsManager for configurable tool exclusion.

* Document CLAUDE_MEM_SKIP_TOOLS setting in public docs

Added documentation for the new CLAUDE_MEM_SKIP_TOOLS configuration
setting in response to PR review feedback. Users can now discover and
customize which tools are excluded from observations.

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

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

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

docs/context/point-audit.md

@@ -0,0 +1,83 @@
+# Claude-Mem Hooks Cleanup Todo
+
+## ✅ Phase 1: Delete Dead Code (Modified)
+
+**hook-response.ts**
+
+- [ ] Remove `| string` from HookType union to restore type safety
+- [ ] Delete PreCompact branch (lines 23-36, 14 lines)
+- [x] ~~Delete pointless branches~~ — SKIP (intentional)
+- [x] ~~Simplify wrapper function~~ — SKIP (intentional)
+
+**new-hook.ts**
+
+- [ ] Delete 34-line architecture comment block (lines 1-34)
+- [ ] Replace 18 lines of debug logging with single 4-line log call (lines 64-81)
+
+**cleanup-hook.ts**
+
+- [ ] Remove `cwd`, `transcript_path`, `hook_event_name` from SessionEndInput interface
+- [ ] Replace 12-line manual mode help with simple error throw
+
+**user-message-hook.ts**
+
+- [ ] Delete all 40 lines of expired announcement code (lines 31-70)
+- [ ] Add comment explaining exit code 3: `// exit code 3 = show user message that Claude does NOT receive as context`
+
+---
+
+## ✅ Phase 2: Extract Shared Utilities
+
+- [ ] Create `src/shared/hook-error-handler.ts` with `handleWorkerError()`
+- [ ] Update all 4 hooks to use shared error handler (context-hook, new-hook, save-hook, summary-hook)
+- [ ] Create `src/shared/transcript-parser.ts` — merge `extractLastUserMessage` + `extractLastAssistantMessage` into single parameterized function
+- [ ] Create `src/shared/hook-constants.ts` for exit codes, timeouts
+
+---
+
+## ❌ Phase 3: SKIPPED
+
+_(Entry points stay as-is, hook-response.ts wrapper stays as-is)_
+
+---
+
+## ✅ Phase 4: Restore Type Safety
+
+**context-hook.ts**
+
+- [ ] Make `session_id`, `cwd`, `transcript_path` required in SessionStartInput
+- [ ] Remove `[key: string]: any`
+- [ ] Remove unused `source` field
+- [ ] Keep using `happy_path_error__with_fallback` for defaults (hooks use exit codes, logging tool is appropriate)
+
+**All 4 hook interfaces**
+
+- [ ] Remove `[key: string]: any` from all interfaces
+
+**save-hook.ts**
+
+- [ ] Keep `happy_path_error__with_fallback` usage (it's appropriate for hook context)
+
+**summary-hook.ts**
+
+- [ ] Add timeout (2s) and error logging to spinner stop request
+
+---
+
+## ✅ Phase 5: Relocate Business Logic (Modified)
+
+- [ ] Move `SKIP_TOOLS` from save-hook.ts to worker service
+- [ ] Make `SKIP_TOOLS` configurable via settings.json
+- [x] ~~Move announcements to database~~ — SKIP
+- [x] ~~Merge context-hook + user-message-hook~~ — SKIP (intentionally separate)
+
+---
+
+## Summary
+
+| Action            | Count |
+| ----------------- | ----- |
+| Lines to delete   | ~150  |
+| New shared files  | 3     |
+| Interfaces to fix | 4     |
+| Items skipped     | 5     |

docs/public/configuration.mdx

@@ -16,6 +16,7 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
 | `CLAUDE_MEM_MODEL`            | `claude-haiku-4-5`              | AI model for processing observations  |
 | `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | `50`                        | Number of observations to inject      |
 | `CLAUDE_MEM_WORKER_PORT`      | `37777`                         | Worker service port                   |
+| `CLAUDE_MEM_SKIP_TOOLS`       | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |
 
 ### System Configuration
 
@@ -353,6 +354,29 @@ Then restart the worker:
 npm run worker:restart
 ```
 
+### Custom Skip Tools
+
+Control which tools are excluded from observations. Edit `~/.claude-mem/settings.json`:
+```json
+{
+  "CLAUDE_MEM_SKIP_TOOLS": "ListMcpResourcesTool,SlashCommand,Skill"
+}
+```
+
+**Default excluded tools:**
+- `ListMcpResourcesTool`
+- `SlashCommand`
+- `Skill`
+- `TodoWrite`
+- `AskUserQuestion`
+
+**Common customizations:**
+- Include TodoWrite: Remove from skip list to track task planning
+- Include AskUserQuestion: Remove to capture decision-making conversations
+- Skip additional tools: Add tool names to reduce observation noise
+
+Changes take effect on the next tool execution (no worker restart needed).
+
 ## Advanced Configuration
 
 ### Hook Timeouts