Hooks

Hooks are lifecycle scripts that run automatically at specific points during agent execution. They are external bash scripts with zero LLM context cost. They execute outside the model and return results via JSON.

Hook Types

Type	When	Purpose
`sessionStart`	New agent session begins	Auto-detection, environment setup
`postToolUse`	After an agent uses a tool	Validation, linting
`sessionEnd`	Session ends	Cleanup

Configuration lives in hooks.json with command path and timeout (default 30 seconds).

Hooks Reference

detect-repo-platform.sh

Type: sessionStart (10s timeout)

Checks git remote URL. Classifies as GitHub (github.com) or Azure DevOps (dev.azure.com / visualstudio.com). Seeds .memory/board-config.md.

detect-branching-strategy.sh

Type: sessionStart (10s timeout)

Analyzes branch naming patterns. Identifies GitFlow (develop/release/hotfix branches) or Trunk-based (main/feature branches). Seeds .memory/git-config.md.

detect-tool-extensions.sh

Type: sessionStart (10s timeout)

Checks if consumer tool extensions are synced with the current plugin version. Warns if extensions are stale or unsynced.

validate-work-item-tags.sh

Type: postToolUse (10s timeout)

After work item creation or update, validates required tags: copilot-generated and ai-model:*. Ensures AI traceability.

lint-markdown.sh

Type: postToolUse (10s timeout)

Runs markdownlint against .markdownlint.yaml config after markdown file edits. Reports formatting issues.

Hook Output

Hooks return JSON on stdout with results. Stderr is used for descriptive error messages. All hooks must:

Include a bash shebang (#!/bin/bash or #!/usr/bin/env bash)
Output JSON on a single line
Complete within their configured timeout. Built-in hooks use a 10-second timeout. The schema default is 30 seconds, configurable per hook via timeoutSec
Be idempotent (safe to run multiple times)

Hooks

Hook Types

Hooks Reference

Hook Output

What to Read Next