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 Contract

PostToolUse validation hooks return structured JSON designed for agent self-correction. Hooks that validate or lint agent output must produce output following this contract:

{
  "decision": "block | warn | info",
  "reason": "Human-readable summary of what was found",
  "instructions": "Step-by-step fix instructions the agent should follow",
  "files": ["path/to/affected/file"],
  "severity": "critical | major | minor"
}

Field	Required	Description
`decision`	Yes	`block` = agent must fix before continuing. `warn` = agent should fix but may continue. `info` = informational only.
`reason`	Yes	What was found, in plain language
`instructions`	Yes	Actionable steps the agent should take to fix the issue. This is the key field: it tells the agent how to fix, not just what broke.
`files`	No	Array of affected file paths (empty array if not file-specific)
`severity`	No	`critical`, `major`, or `minor`. Defaults to `minor` if omitted.

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 (use jq -nc to construct)
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 Contract

What to Read Next