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.

detect-lsp-servers.sh

Type: sessionStart (10s timeout)

Records whether .github/lsp.json and ~/.copilot/lsp-config.json exist in .memory/lsp-status.md. When neither exists, warns only if recognizable source files or build manifests exist outside excluded scaffolding, documentation/examples, templates, dependencies, and generated output. Otherwise, records deferred setup without warning so new repositories can proceed with planning. The lightweight scan does not cover every language; setup can still be requested explicitly. For missing CLI support, recommends /lsp and the lsp-setup skill. Configuration presence does not establish language coverage or server health. Plugin-provided servers and VS Code language services are not checked. The hook never installs or starts servers.

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