feat: add notification hook for user input prompts (#1415)

* feat: add notification hook for user input prompts

Add Linux desktop notification hook that triggers when Claude Code
is awaiting user input. This is the first hook implementation in the
project and establishes the pattern for future hooks.

The hook uses notify-send to display system notifications in two scenarios:
- When Claude requests tool usage permission
- When the prompt input remains idle for 60+ seconds

Configuration added to .claude/settings.json (version-controlled) to
make notifications available project-wide.

Closes #1414

* docs: add comprehensive hooks configuration documentation

Add detailed hooks section to claude-code-settings.md explaining:
- Hook structure and syntax
- Available hook events and their purposes
- Matcher field behavior with comparison table
- Important distinction between empty string and wildcard matchers
- Current notification hook configuration and prerequisites
- Security best practices for hook implementation

This documentation establishes the pattern for future hook implementations
and clarifies the non-intuitive empty string matcher for Notification hooks.

* refactor: simplify hooks documentation to link official docs

Replace detailed hook documentation with links to authoritative sources:
- https://docs.claude.com/en/docs/claude-code/hooks
- https://docs.claude.com/en/docs/claude-code/hooks-guide

Keep only project-specific information about implemented hooks.
Avoids duplicating official docs that may change over time.

* Update .claude/settings.json

Co-authored-by: amazon-q-developer[bot] <208079219+amazon-q-developer[bot]@users.noreply.github.com>

---------

Co-authored-by: amazon-q-developer[bot] <208079219+amazon-q-developer[bot]@users.noreply.github.com>

Author: atxtechbro

.claude/settings.json

@@ -64,5 +64,18 @@
     "dotfiles-commands@dotfiles-marketplace": true
   },
   "forceLoginMethod": "claudeai",
-  "alwaysThinkingEnabled": true
+  "alwaysThinkingEnabled": true,
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+"command": "notify-send 'Claude Code' 'Awaiting your input - please check the terminal'"
+          }
+        ]
+      }
+    ]
+  }
 }

docs/claude-code-settings.md

@@ -55,6 +55,44 @@ Environment variables configured:
 - `MCP_TOOL_TIMEOUT`: 60000 - MCP tool execution timeout
 - `MAX_MCP_OUTPUT_TOKENS`: 25000 - Maximum tokens in MCP responses
 
+## Hooks Configuration
+
+Hooks allow you to execute custom commands in response to Claude Code events. They are configured in `.claude/settings.json` under the `"hooks"` key.
+
+**Official Documentation:**
+- [Hooks Reference](https://docs.claude.com/en/docs/claude-code/hooks) - Available events, matcher syntax, and configuration structure
+- [Hooks Guide](https://docs.claude.com/en/docs/claude-code/hooks-guide) - Examples and best practices
+
+### Hooks Implemented in This Project
+
+#### Notification Hook (Issue #1414)
+Displays Linux desktop notifications when Claude Code is awaiting user input.
+
+**Triggers:**
+- When Claude requests tool usage permission
+- When the prompt input remains idle for 60+ seconds
+
+**Configuration:**
+```json
+"Notification": [
+  {
+    "matcher": "",
+    "hooks": [
+      {
+        "type": "command",
+        "command": "notify-send 'Claude Code' 'Awaiting your input'"
+      }
+    ]
+  }
+]
+```
+
+**Prerequisites:**
+- Linux: `libnotify-bin` package (installed via `sudo apt install libnotify-bin`)
+- macOS: Native notification system (no additional packages required)
+
+**Note:** For `Notification` hooks, the matcher is an empty string (`""`), not `"*"`, since notification events are not tool-specific.
+
 ## Adding New Settings
 
 1. Add the setting to `.claude/settings/claude-code-defaults.json`