# Hooks System

**Status**: ✅ Complete

**Phase**: Phase 3 - Advanced Features

**Last Updated**: December 5, 2025

---

## Overview

The Hooks System enables event-driven automation through a registry of hooks that trigger on specific events. Hooks can execute shell commands, call ricecoder tools directly with parameters, or trigger other hooks in chains. This allows you to automate repetitive tasks and integrate ricecoder with external tools seamlessly.

## Key Features

- **Event-Driven Automation**: Hooks trigger automatically on system events (file operations, test results, generation completion)
- **Multiple Action Types**: Execute shell commands, call tools with parameter binding, send prompts to AI assistants, or chain hooks together
- **Configuration-Driven**: Define hooks in YAML configuration files without code changes
- **Variable Substitution**: Use event context variables in commands, tool parameters, and AI prompts
- **Hook Chaining**: Execute hooks in sequence with output passing between them
- **Conditional Execution**: Execute hooks only when specific conditions are met
- **Hot-Reload**: Configuration changes are detected and reloaded without restart
- **Hook Management**: List, inspect, enable, disable, and delete hooks via CLI

## Quick Start

### 1. Create a Hook Configuration

Create `.ricecoder/hooks.yaml` in your project:

```yaml
hooks:
  - name: "Format on save"
    event: "file_modified"
    action:
      type: "command"
      command: "prettier"
      args:
        - "{{file_path}}"
    enabled: true
```

### 2. List Hooks

```bash
ricecoder hooks list
```

### 3. Inspect a Hook

```bash
ricecoder hooks inspect <hook-id>
```

### 4. Enable/Disable Hooks

```bash
ricecoder hooks enable <hook-id>
ricecoder hooks disable <hook-id>
```

## How to Use

### Basic Hook Configuration

A hook consists of:
- **name**: Human-readable hook name
- **event**: Event type that triggers the hook (e.g., `file_modified`, `test_passed`)
- **action**: What to execute when the hook is triggered
- **enabled**: Whether the hook is active (default: true)
- **condition** (optional): Condition that must be met to execute the hook
- **tags** (optional): Tags for organizing hooks
- **metadata** (optional): Custom metadata

### Action Types

#### 1. Command Action

Execute a shell command:

```yaml
action:
  type: "command"
  command: "echo"
  args:
    - "File modified: {{file_path}}"
  timeout_ms: 5000
  capture_output: true
```

#### 2. Tool Call Action

Call a ricecoder tool with parameter binding:

```yaml
action:
  type: "tool_call"
  tool_name: "code_formatter"
  tool_path: "/usr/local/bin/prettier"
  parameters:
    file_path: "{{file_path}}"
    output_dir: "/tmp/formatted"
  timeout_ms: 10000
```

#### 3. AI Prompt Action

Send a prompt to an AI assistant with context:

```yaml
action:
  type: "ai_prompt"
  prompt_template: |
    Review this code change:
    File: {{file_path}}
    Old hash: {{old_hash}}
    New hash: {{new_hash}}
    
    Provide feedback on the changes.
  model: "gpt-4"
  temperature: 0.7
  stream: true
```

#### 4. Chain Action

Execute multiple hooks in sequence:

```yaml
action:
  type: "chain"
  hook_ids:
    - "format-hook-id"
    - "lint-hook-id"
    - "test-hook-id"
  pass_output: true
```

### Available Events

#### File Operations

- `file_created` - When a file is created
- `file_modified` - When a file is modified
- `file_deleted` - When a file is deleted
- `file_renamed` - When a file is renamed
- `file_moved` - When a file is moved
- `file_read` - When a file is read
- `directory_created` - When a directory is created
- `directory_deleted` - When a directory is deleted

#### System Events

- `test_passed` - When tests pass
- `test_failed` - When tests fail
- `generation_complete` - When code generation completes
- `build_complete` - When build completes
- `deployment_complete` - When deployment completes

### Variable Substitution

Use event context variables in your hooks:

```yaml
action:
  type: "command"
  command: "echo"
  args:
    - "File: {{file_path}}"
    - "Size: {{file_size}}"
    - "Hash: {{file_hash}}"
```

Available variables depend on the event type. See [Hooks Variables Guide](./Hooks-Variables.md) for complete reference.

### Conditional Execution

Execute hooks only when conditions are met:

```yaml
hooks:
  - name: "Format TypeScript files"
    event: "file_modified"
    condition:
      expression: "file_path.endsWith('.ts')"
    action:
      type: "command"
      command: "prettier"
      args:
        - "{{file_path}}"
```

### Hook Chaining

Execute hooks in sequence with output passing:

```yaml
hooks:
  - name: "Format and lint"
    event: "file_modified"
    action:
      type: "chain"
      hook_ids:
        - "format-hook"
        - "lint-hook"
      pass_output: true
```

## Configuration

### Configuration Hierarchy

Hooks are loaded from multiple sources in priority order:

1. **Runtime**: Configuration passed programmatically
2. **Project**: `.ricecoder/hooks.yaml` (project-specific)
3. **User**: `~/.ricecoder/hooks.yaml` (user-level)
4. **Built-in**: Built-in hook templates and defaults

### Configuration File Format

See [Hooks Configuration Guide](./Hooks-Configuration.md) for detailed configuration options and examples.

## Examples

### Example 1: Auto-Format on Save

```yaml
hooks:
  - name: "Auto-format on save"
    event: "file_modified"
    action:
      type: "command"
      command: "prettier"
      args:
        - "--write"
        - "{{file_path}}"
    enabled: true
```

### Example 2: Run Tests on Save

```yaml
hooks:
  - name: "Run tests on save"
    event: "file_modified"
    condition:
      expression: "file_path.endsWith('.test.ts')"
    action:
      type: "command"
      command: "npm"
      args:
        - "test"
        - "{{file_path}}"
    enabled: true
```

### Example 3: AI Code Review

```yaml
hooks:
  - name: "AI code review"
    event: "file_modified"
    action:
      type: "ai_prompt"
      prompt_template: |
        Review this code change:
        File: {{file_path}}
        
        Provide constructive feedback.
      model: "gpt-4"
      stream: true
    enabled: true
```

### Example 4: Tool Integration

```yaml
hooks:
  - name: "Format with custom tool"
    event: "file_modified"
    action:
      type: "tool_call"
      tool_name: "custom_formatter"
      tool_path: "./tools/formatter"
      parameters:
        file_path: "{{file_path}}"
        style: "prettier"
    enabled: true
```

## Troubleshooting

### Hook Not Triggering

**Problem**: Hook is configured but not executing when event occurs.

**Solutions**:
1. Verify hook is enabled: `ricecoder hooks inspect <hook-id>`
2. Check event name matches exactly (case-sensitive)
3. Verify condition expression is correct
4. Check hook configuration syntax in YAML file
5. Review logs for errors: `ricecoder logs --filter hooks`

### Hook Execution Fails

**Problem**: Hook executes but fails with error.

**Solutions**:
1. Check command/tool path is correct and executable
2. Verify all required parameters are provided
3. Check variable substitution is working: `ricecoder hooks inspect <hook-id>`
4. Increase timeout if hook needs more time
5. Review error message in logs

### Variable Substitution Not Working

**Problem**: Variables like `{{file_path}}` are not being replaced.

**Solutions**:
1. Verify variable name matches event context (case-sensitive)
2. Check event type provides the variable
3. Use `ricecoder hooks inspect` to see available variables
4. See [Hooks Variables Guide](./Hooks-Variables.md) for complete reference

### Configuration Not Reloading

**Problem**: Changes to hooks.yaml are not taking effect.

**Solutions**:
1. Verify file is saved
2. Wait a moment for file watcher to detect change
3. Check file permissions are readable
4. Restart ricecoder if hot-reload fails
5. Check logs for configuration errors

## Performance

- Simple hooks (command execution): < 100ms
- Complex hooks (tool calls, AI prompts): < 1s
- Configuration loading: < 500ms
- Hook management operations: < 50ms

## Limitations

- Hooks execute sequentially (not in parallel)
- Maximum timeout: 60 seconds per hook
- Maximum chain depth: 10 hooks
- Configuration file size: < 10MB

## See Also

- [Hooks Configuration Guide](./Hooks-Configuration.md) - Detailed configuration options
- [Hooks Events Guide](./Hooks-Events.md) - Available events and context
- [Hooks Actions Guide](./Hooks-Actions.md) - Action types and examples
- [Hooks Variables Guide](./Hooks-Variables.md) - Variable substitution reference
- [Architecture Overview](./Architecture-Overview.md) - System architecture
- [Troubleshooting Guide](./Troubleshooting.md) - General troubleshooting

---

*Last updated: December 5, 2025*