Hooks Variables

Hooks Variables Guide

Status: ✅ Complete

Last Updated: December 5, 2025

---

Overview

This guide documents variable substitution and parameter binding in hooks. Variables allow you to use event context data in hook actions.

Variable Substitution Syntax

Variables are substituted using {{variable_name}} syntax:

action:
  type: "command"
  command: "echo"
  args:
    - "File: {{file_path}}"
    - "Size: {{file_size}}"

Variable Types

Literal Variables

Direct values from event context:

args:
  - "{{file_path}}"
  - "{{file_size}}"

Nested Variables

Access nested properties with dot notation:

args:
  - "{{metadata.size}}"
  - "{{context.user_id}}"

Expression Variables

Mix literal text with variables:

args:
  - "{{file_path}}/subdir"
  - "output-{{timestamp}}.txt"

File Operation Variables

file_created Event

Available variables:

• file_path: Path to the created file
• size: File size in bytes
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Created: {{file_path}} ({{size}} bytes)"

file_modified Event

Available variables:

• file_path: Path to the modified file
• old_hash: Hash of the file before modification
• new_hash: Hash of the file after modification
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Modified: {{file_path}}"
    - "Old: {{old_hash}}"
    - "New: {{new_hash}}"

file_deleted Event

Available variables:

• file_path: Path to the deleted file
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Deleted: {{file_path}}"

file_renamed Event

Available variables:

• old_path: Previous file path
• new_path: New file path
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Renamed: {{old_path}} -> {{new_path}}"

file_moved Event

Available variables:

• old_path: Previous file path
• new_path: New file path
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Moved: {{old_path}} -> {{new_path}}"

file_read Event

Available variables:

• file_path: Path to the read file
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Read: {{file_path}}"

Directory Operation Variables

directory_created Event

Available variables:

• directory_path: Path to the created directory
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Directory created: {{directory_path}}"

directory_deleted Event

Available variables:

• directory_path: Path to the deleted directory
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Directory deleted: {{directory_path}}"

System Event Variables

test_passed Event

Available variables:

• test_file: Path to the test file
• test_count: Number of tests that passed
• duration_ms: Test execution duration in milliseconds
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Tests passed: {{test_count}} tests in {{duration_ms}}ms"

test_failed Event

Available variables:

• test_file: Path to the test file
• failed_count: Number of tests that failed
• passed_count: Number of tests that passed
• duration_ms: Test execution duration in milliseconds
• error_message: Error message from the first failure
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "ai_prompt"
  prompt_template: |
    Tests failed:
    Failed: {{failed_count}}
    Passed: {{passed_count}}
    Error: {{error_message}}
    
    Suggest fixes.

generation_complete Event

Available variables:

• generated_files: Number of files generated
• total_lines: Total lines of code generated
• duration_ms: Generation duration in milliseconds
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Generated {{generated_files}} files ({{total_lines}} lines)"

build_complete Event

Available variables:

• build_status: Build status (success/failure)
• output_dir: Output directory path
• duration_ms: Build duration in milliseconds
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Build {{build_status}} in {{duration_ms}}ms"

deployment_complete Event

Available variables:

• deployment_status: Deployment status (success/failure)
• environment: Deployment environment (production/staging/etc)
• version: Deployed version
• duration_ms: Deployment duration in milliseconds
• timestamp: ISO 8601 timestamp

Example:

action:
  type: "command"
  command: "echo"
  args:
    - "Deployed v{{version}} to {{environment}}"

Parameter Binding

Parameter binding uses variable substitution to bind event context to tool parameters:

action:
  type: "tool_call"
  tool_name: "formatter"
  tool_path: "/usr/local/bin/prettier"
  parameters:
    file_path: "{{file_path}}"           # From event context
    output_dir: "/tmp/formatted"         # Literal value
    style: "prettier"                    # Literal value

Binding Types

Literal Binding

Use literal values directly:

parameters:
  style: "prettier"
  config: ".prettierrc.json"

Variable Binding

Use event context variables:

parameters:
  file_path: "{{file_path}}"
  old_hash: "{{old_hash}}"

Expression Binding

Mix literal text with variables:

parameters:
  output_path: "{{file_path}}.formatted"
  backup_path: "/tmp/backup-{{timestamp}}.bak"

Variable Availability

Variables are only available if the event provides them. Using an unavailable variable will result in an error.

Checking Available Variables

Use ricecoder hooks inspect <hook-id> to see available variables for a hook's event:

$ ricecoder hooks inspect format-hook
Hook: format-hook
Event: file_modified
Available variables:
  - file_path
  - old_hash
  - new_hash
  - timestamp

Missing Variables

If a variable is not available in the event context:

1. Error: Hook execution fails with clear error message
2. Message: Indicates which variable is missing
3. Resolution: Update hook to use available variables

Example Error:

Error: Variable "file_size" not available in event context
Available variables: file_path, old_hash, new_hash, timestamp

Variable Escaping

Special characters in variables are automatically escaped:

args:
  - "{{file_path}}"  # Automatically escaped for shell

Common Patterns

Pattern 1: File Path Manipulation

action:
  type: "command"
  command: "echo"
  args:
    - "Processing: {{file_path}}"

Pattern 2: Hash Comparison

action:
  type: "command"
  command: "echo"
  args:
    - "Changed from {{old_hash}} to {{new_hash}}"

Pattern 3: Timestamp Logging

action:
  type: "command"
  command: "echo"
  args:
    - "[{{timestamp}}] File modified: {{file_path}}"

Pattern 4: Test Results

action:
  type: "command"
  command: "echo"
  args:
    - "Tests: {{passed_count}} passed, {{failed_count}} failed"

Pattern 5: Tool Parameter Binding

action:
  type: "tool_call"
  tool_name: "formatter"
  tool_path: "/usr/local/bin/prettier"
  parameters:
    file_path: "{{file_path}}"
    output_dir: "/tmp/formatted"

Troubleshooting

Variable Not Substituting

Problem: Variable like {{file_path}} is not being replaced.

Solutions:

1. Verify variable name is correct (case-sensitive)
2. Check event type provides the variable
3. Use ricecoder hooks inspect to see available variables
4. Verify variable syntax is correct: {{variable_name}}

Missing Variable Error

Problem: Hook fails with "variable not available" error.

Solutions:

1. Check which variables are available for the event
2. Use ricecoder hooks inspect to see available variables
3. Update hook to use available variables
4. See event documentation for available variables

Special Characters in Variables

Problem: Variable values contain special characters that break commands.

Solutions:

1. Variables are automatically escaped for shell
2. For tool parameters, use literal values for special characters
3. Use quotes around variable substitutions if needed

See Also

• Hooks System Guide - Main hooks guide
• Hooks Configuration Guide - Configuration options
• Hooks Events Guide - Available events
• Hooks Actions Guide - Action types
• Troubleshooting Guide - General troubleshooting

---

Last updated: December 5, 2025