Merge pull request #324 from neongreen/copilot/add-global-install-flag

aihook: Add prevent-stop hook and --install flag

Author: neongreen

aihook/AGENTS.md

@@ -2,25 +2,34 @@
 
 ## Project Overview
 
-`aihook` is a validator for Claude Code hooks that enforces shell scripting best practices. The primary use case is validating that `cd` commands are always executed within subshells.
+`aihook` is a toolkit for Claude Code hooks that provides validators and behavior modifiers. It includes:
+- Shell validation hook to enforce `cd` commands are always executed within subshells
+- Prevent-stop hook to prevent Claude from stopping prematurely
+- Global `--install` flag to add hooks to `~/.claude/settings.json`
 
 ## Project Structure
 
 ```
 aihook/
 ├── main.go                      # CLI entry point (Cobra setup)
 ├── pkg/
+│   ├── installer/
+│   │   ├── installer.go         # Hook installation to ~/.claude/settings.json
+│   │   └── installer_test.go    # Installer tests
 │   └── validator/
 │       ├── validator.go         # Core validation logic
 │       └── validator_test.go    # Comprehensive unit tests
+├── hook_response_test.go        # Tests for hook response functions
+├── integration_test.go          # Integration tests
 ├── README.md                    # User documentation
 └── AGENTS.md                    # This file
 ```
 
 **Separation of concerns:**
-- `main.go`: Cobra CLI setup, flag handling, output formatting
+- `main.go`: Cobra CLI setup, flag handling, output formatting, hook commands
 - `pkg/validator`: Pure validation logic (AST walking, cd detection)
-- Tests are in the validator package, testing the pure logic
+- `pkg/installer`: Installation logic for adding hooks to Claude settings
+- Tests are in each package, testing the pure logic
 
 ## Development Guidelines
 
@@ -33,35 +42,50 @@ Always run tests and build from the repository root:
 go test ./aihook/...
 
 # Build
-go build ./aihook
+go build -o /tmp/aihook ./aihook
 
 # Run
-./aihook shell < script.sh
+/tmp/aihook shell < script.sh
+/tmp/aihook prevent-stop --install
 ```
 
 ### Code Structure
 
-- `main.go` (86 lines) - CLI entry point with Cobra framework
-  - Command definitions and flag handling
+- `main.go` - CLI entry point with Cobra framework
+  - Command definitions (shell, prevent-stop)
+  - Global `--install` flag
   - Output formatting (regular and --claude JSON)
-  - Calls into validator package for logic
+  - Hook response functions
 
-- `pkg/validator/validator.go` (106 lines) - Core validation logic
+- `pkg/validator/validator.go` - Core validation logic
   - `Validator` type with `ValidateScript()` method
   - AST walking to detect cd commands
   - Tracks subshell context (both `(...)` and `$(...)`)
   - `FormatViolations()` for user-friendly error messages
 
-- `pkg/validator/validator_test.go` (330 lines) - Comprehensive tests
-  - 41 test scenarios covering all edge cases
-  - Tests the validator package directly
+- `pkg/installer/installer.go` - Hook installation
+  - `InstallHook()` function to add hooks to `~/.claude/settings.json`
+  - Handles creating the settings file if it doesn't exist
+  - Prevents duplicate hook installation
+
+### Available Commands
+
+1. **`shell`**: Validates Bash commands to ensure `cd` is only used in subshells
+   - `--claude`: Output in JSON format
+   - `--block-on-cd`: Deny execution when violations found
+
+2. **`prevent-stop`**: Prevents Claude from stopping prematurely
+   - Returns `continue: false` with a message telling Claude to keep working
+
+3. **`--install` (global flag)**: Installs the hook to `~/.claude/settings.json`
 
 ### Key Implementation Details
 
 1. **Shell Parsing**: Uses `mvdan.cc/sh/v3/syntax` for accurate shell script parsing
 2. **AST Walking**: Traverses the syntax tree to find `cd` commands and track subshell context
 3. **Subshell Detection**: Handles both explicit subshells `(...)` and command substitutions `$(...)`
 4. **Output Formats**: Supports both human-readable and Claude Code JSON formats
+5. **Hook Installation**: Modifies `~/.claude/settings.json` to add hooks
 
 ### Testing Philosophy
 
@@ -72,6 +96,9 @@ Tests cover:
 - Edge cases (loops, conditionals, functions)
 - Invalid shell syntax
 - Multiple cd commands in one script
+- Hook installation to settings file
+- Duplicate installation prevention
+- Hook response JSON structure
 
 All tests must pass before any changes are committed.
 
@@ -81,29 +108,39 @@ All tests must pass before any changes are committed.
 2. **Command Substitution**: `$(...)` IS a subshell and cd is allowed inside
 3. **Here Documents**: Content inside here-docs should not be parsed as commands
 
-### Claude Code Hook Format
+### Claude Code Hook Response Format
 
-When `--claude` flag is used, output must be JSON with:
-- `exit_code`: Integer (0 for success, 2 for violations, 1 for errors)
-- `message`: String containing the human-readable message
+For PreToolUse hooks:
+```json
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow|deny",
+    "permissionDecisionReason": "..."
+  }
+}
+```
 
-Example:
+For Stop hooks (prevent-stop):
 ```json
 {
-  "exit_code": 2,
-  "message": "Found cd commands outside subshells:\n  Line 1: 'cd' command found outside subshell\n\nAll 'cd' commands must be in a subshell. Example:\n  # Bad:  cd /tmp && ls\n  # Good: (cd /tmp && ls)\n"
+  "continue": false,
+  "stopReason": "Keep working!",
+  "systemMessage": "Continue working on the task..."
 }
 ```
 
 ## Adding New Hook Types
 
-When adding new hook types in the future:
+When adding new hook types:
 
 1. Add a new subcommand in `main.go`
 2. Create a new validator in `pkg/validator` if needed
-3. Add comprehensive unit tests in the validator package
-4. Update README.md with usage examples
-5. Update this AGENTS.md with implementation notes
+3. Add support in `pkg/installer` for the new event type
+4. Add comprehensive unit tests
+5. Update README.md with usage examples
+6. Update this AGENTS.md with implementation notes
 
 ## Dependencies
 

aihook/README.md

@@ -1,22 +1,18 @@
 # aihook
 
-A validator for Claude Code hooks that enforces shell scripting best practices.
+A toolkit for Claude Code hooks including validators and behavior modifiers.
 
 ## Overview
 
-`aihook` is a command-line tool designed to validate shell scripts for use in Claude Code PreToolUse hooks. It parses shell syntax and enforces specific rules to ensure code quality and consistency.
+`aihook` is a command-line tool that provides various hooks for Claude Code. It can validate shell scripts and modify Claude's behavior (like preventing premature stopping).
 
 ## Features
 
-- **PreToolUse Hook**: Validates Bash commands before execution to forbid `cd` invocations outside subshells
+- **Shell Validation Hook**: Validates Bash commands before execution to forbid `cd` invocations outside subshells
+- **Prevent-Stop Hook**: Prevents Claude from stopping prematurely, forcing it to continue working
+- **Global Install**: Use `--install` flag to add hooks to `~/.claude/settings.json` automatically
 - **Shell Parser**: Uses `mvdan.cc/sh/v3/syntax` for accurate shell script parsing
-- **Claude Code Integration**: Supports `--claude` flag for JSON output compatible with Claude Code hooks
-- **Comprehensive Validation**: Handles complex scenarios including:
-  - Nested subshells
-  - Command substitution (`$(...)`)
-  - Conditional statements
-  - Loops and functions
-  - Here documents
+- **Claude Code Integration**: Supports JSON output compatible with Claude Code hooks
 
 ## Installation
 
@@ -29,11 +25,47 @@ go install github.com/neongreen/mono/aihook@latest
 ### Local Development
 
 ```bash
-go build ./aihook
+go build -o /tmp/aihook ./aihook
 ```
 
 ## Usage
 
+### Global --install Flag
+
+All hooks support the `--install` flag which adds the hook to your global Claude settings (`~/.claude/settings.json`) instead of running it:
+
+```bash
+# Install the prevent-stop hook
+aihook prevent-stop --install
+
+# Install the shell hook
+aihook shell --install
+
+# Install shell hook with block-on-cd behavior
+aihook shell --install --block-on-cd
+```
+
+### Prevent-Stop Hook
+
+The `prevent-stop` subcommand prevents Claude from stopping prematurely:
+
+```bash
+# Run as a hook (reads JSON input from stdin)
+echo '{}' | aihook prevent-stop
+
+# Install to global Claude settings
+aihook prevent-stop --install
+```
+
+Output when running:
+```json
+{
+  "continue": false,
+  "stopReason": "Keep working! Don't stop until the task is fully complete.",
+  "systemMessage": "You are not done yet. Continue working on the task until it is fully complete. Do not stop prematurely."
+}
+```
+
 ### Shell Hook
 
 The `shell` subcommand validates shell scripts and ensures all `cd` commands are executed within subshells:
@@ -47,6 +79,9 @@ echo 'cd /tmp' | aihook shell --claude
 
 # Block execution when cd violations are found
 echo 'cd /tmp' | aihook shell --claude --block-on-cd
+
+# Install to global Claude settings
+aihook shell --install --block-on-cd
 ```
 
 ### Examples
@@ -63,6 +98,10 @@ cd /tmp && ls
 
 ### Flags
 
+Global flags:
+- `--install`: Install hook to global Claude settings (`~/.claude/settings.json`) instead of running it
+
+Shell hook flags:
 - `--claude`: Output in JSON format compatible with Claude Code hooks
 - `--block-on-cd`: When set, returns exit code 2 for violations (blocks execution). Without this flag, violations are reported but execution is not blocked (exit code 0)
 
@@ -87,14 +126,20 @@ All 'cd' commands must be in a subshell. Example:
 #### Claude Code Hook Format (`--claude`)
 ```json
 {
-  "exit_code": 2,
-  "message": "Found cd commands outside subshells:\n  Line 1: 'cd' command found outside subshell\n\nAll 'cd' commands must be in a subshell. Example:\n  # Bad:  cd /tmp && ls\n  # Good: (cd /tmp && ls)\n"
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Found cd commands outside subshells..."
+  }
 }
 ```
 
 ## Claude Code Integration
 
-To use `aihook` as a Claude Code PreToolUse hook that validates Bash commands, add this to your `.claude/settings.json`:
+### Manual Configuration
+
+To use `aihook` as a Claude Code hook, add this to your `.claude/settings.json`:
 
 ```json
 {
@@ -109,20 +154,35 @@ To use `aihook` as a Claude Code PreToolUse hook that validates Bash commands, a
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": "stop",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "aihook prevent-stop"
+          }
+        ]
+      }
     ]
   }
 }
 ```
 
-The hook will:
-- Match any Bash tool invocation (via the `"Bash"` matcher)
-- Receive the bash command script on stdin
-- Validate that all `cd` commands are in subshells
-- With `--block-on-cd`: Return exit code 2 to block execution when violations are found
-- Without `--block-on-cd`: Report violations but allow execution (exit code 0)
-- Use `--claude` flag to output in the expected JSON format
+### Automatic Installation
+
+Use the `--install` flag to automatically add hooks to your global Claude settings:
+
+```bash
+# Install prevent-stop hook
+aihook prevent-stop --install
+
+# Install shell hook with cd blocking
+aihook shell --install --block-on-cd
+```
 
-For more flexible matching, you can use regex patterns like `"Bash.*cd"` to only check Bash commands containing `cd`.
+The hooks will be added to `~/.claude/settings.json`, creating the file if it doesn't exist.
 
 ## Why Forbid cd Outside Subshells?
 
@@ -143,13 +203,13 @@ By requiring `cd` in subshells `(cd /path && command)`, you ensure:
 ### Running Tests
 
 ```bash
-go test ./aihook -v
+go test ./aihook/... -v
 ```
 
 ### Building
 
 ```bash
-go build ./aihook
+go build -o /tmp/aihook ./aihook
 ```
 
 ## License