Hook Development

Hook Development for Copilot CLI Plugins

Create event-driven hooks that validate operations, enforce policies, add context, and integrate external tools into Copilot CLI workflows.

• Validate tool calls before execution (preToolUse)
• React to tool results (postToolUse)
• Enforce completion standards (agentStop, subagentStop)
• Load project context (sessionStart)
• Automate workflows across the development lifecycle

Hook Types

Command Hooks

Execute commands for deterministic checks:

{
  "type": "command",
  "command": "bash hooks/scripts/validate.sh",
  "timeout": 60000
}

Use for:

• Fast deterministic validations
• File system operations
• External tool integrations
• Performance-critical checks

Hook Configuration Formats

Plugin hooks.json Format

For plugin hooks in hooks/hooks.json, use wrapper format:

{
  "description": "Brief explanation of hooks (optional)",
  "hooks": {
    "preToolUse": [...],
    "agentStop": [...],
    "sessionStart": [...]
  }
}

Key points:

• description field is optional
• hooks field is required wrapper containing actual hook events
• This is the plugin-specific format

Example:

{
  "description": "Validation hooks for code quality",
  "hooks": {
    "preToolUse": [
      {
        "matcher": "edit",
        "hooks": [
          {
            "type": "command",
            "command": "hooks/scripts/validate.sh"
          }
        ]
      }
    ]
  }
}

Settings Format (Direct)

For user settings in .github/settings.json, use direct format:

{
  "preToolUse": [...],
  "agentStop": [...],
  "sessionStart": [...]
}

Key points:

• No wrapper - events directly at top level
• No description field
• This is the settings format

Important: The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in {"hooks": {...}}.

Hook Events

preToolUse

Execute before any tool runs. Use to approve, deny, or modify tool calls.