Agent Hooks

VS Code Agent Hooks automate code quality enforcement by running shell commands at key lifecycle points during agent sessions. They complement the instruction-based approach with deterministic, code-driven automation.

Git hooks vs. Agent hooks

This page covers VS Code Agent Hooks (lifecycle events during agent sessions). For git hooks (pre-commit, pre-push, commit-msg via lefthook), see the Validation & Linting Reference.

Preview Feature

Agent hooks are a VS Code Preview feature. Agent-scoped hooks (defined in .agent.md frontmatter) require chat.useCustomAgentHooks: true in .vscode/settings.json.

How Hooks Work

sequenceDiagram
    participant A as 🤖 Agent
    participant H as 🪝 Hook
    participant T as 🔧 Tool

    A->>H: PreToolUse (before tool runs)
    alt Blocked
        H-->>A: deny + reason
    else Allowed
        H-->>A: continue
        A->>T: Execute tool
        T-->>A: Result
        A->>H: PostToolUse (after tool runs)
        H-->>A: continue + advisory
    end

Hook Inventory

Hook Directory	Event(s)	Purpose	Timeout
secrets-scanner/	Stop	Scan for leaked secrets at session end	30s
session-telemetry/	SessionStart, Stop, UserPromptSubmit	Merged session lifecycle logging and governance audit	5–10s
subagent-validation/	SubagentStop	Validate subagent output quality (advisory)	15s
tool-audit/	PostToolUse	Log tool usage metadata (name, status)	5s
tool-guardian/	PreToolUse	Block dangerous terminal commands	10s

Configuration

Hooks are registered in .vscode/settings.json:

{
  "chat.hookFilesLocations": {
    ".github/hooks/secrets-scanner": true,
    ".github/hooks/session-telemetry": true,
    ".github/hooks/subagent-validation": true,
    ".github/hooks/tool-audit": true,
    ".github/hooks/tool-guardian": true
  },
  "chat.useCustomAgentHooks": true
}

Agent-Scoped Hooks

Agents can define hooks in their YAML frontmatter (requires chat.useCustomAgentHooks):

hooks:
  PreToolUse:
    - type: command
      command: "bash .github/hooks/tool-guardian/guard-tool.sh"
      timeout: 10

Do not duplicate global hooks

If a hook is already registered globally in chat.hookFilesLocations, do not re-define it in agent frontmatter — this causes the hook to run twice. Use agent-scoped hooks only for agent-specific logic not covered by global hooks.

Safety Considerations

Infinite Loop Prevention

The Stop hook (session-telemetry/session-end.sh) checks stop_hook_active from stdin JSON. If true, it returns immediately without processing — preventing infinite re-invocation.

Self-Modification Protection

The PreToolUse hook blocks file-edit tools (replace_string_in_file, create_file, etc.) from modifying files under .github/hooks/. Path resolution uses realpath to handle symlinks and traversal attacks (../).

Timeout Enforcement

Each hook specifies a timeout (5-180s). If a hook exceeds its timeout, VS Code terminates it and continues the agent session.

SessionId Sanitization

The Stop hook sanitizes sessionId input to prevent path traversal — only alphanumeric characters, hyphens, and underscores are preserved.

Two-Layer Secrets Defense

Secrets are caught at two independent layers:

• Layer 1 — Pre-commit (gitleaks): Blocks known secret patterns in staged files before they enter git history. Local soft-skip if gitleaks is not installed; CI hard-fail.
• Layer 2 — Session end (secrets-scanner): Regex-based scanner at Stop event catches in-session writes that may not yet be staged. Logs to logs/copilot/secrets/scan.log.

Hook Directory Structure

Each hook follows this pattern:

.github/hooks/{name}/
├── hooks.json          # Event binding + timeout
└── {name}.sh           # Shell script (present at configured path; exec bit optional)

hooks.json Schema

{
  "hooks": {
    "<EventName>": [
      {
        "type": "command",
        "command": "bash .github/hooks/{name}/{name}.sh",
        "timeout": 30
      }
    ]
  }
}

Valid event names: PreToolUse, PostToolUse, SessionStart, SubagentStart, SubagentStop, Stop.

Script Conventions

All hook scripts must:

1. Start with #!/usr/bin/env bash
2. Include set -euo pipefail
3. Read JSON from stdin
4. Write JSON to stdout ({"continue": true} or {"hookSpecificOutput": {...}})
5. Be present at the configured path and be invoked through bash in hooks.json so execution does not depend on the file mode

Validation

# Validate hook configurations
npm run validate:hooks

# Run hook integration tests
npm run test:hooks

Adding a New Hook

1. Create the hook directory and script

mkdir -p .github/hooks/my-hook-name

Create .github/hooks/my-hook-name/my-hook-name.sh:

#!/usr/bin/env bash
set -euo pipefail

INPUT=$(cat)

# Parse input JSON
FIELD=$(echo "$INPUT" | python3 -c \
  "import sys,json; print(json.load(sys.stdin).get('field',''))" \
  2>/dev/null || echo "")

# Your logic here...

# Output JSON safely (prevents injection)
python3 -c "
import json, sys
print(json.dumps({'continue': True, 'systemMessage': sys.argv[1]}))
" "Your message" 2>/dev/null || echo '{"continue": true}'

2. Create hooks.json

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "bash .github/hooks/my-hook-name/my-hook-name.sh",
        "timeout": 30
      }
    ]
  }
}

3. Register in VS Code settings

Add to chat.hookFilesLocations in .vscode/settings.json:

".github/hooks/my-hook-name": true

4. Add tests and validate

Add test cases to tools/scripts/test-hooks.sh, then run:

npm run validate:hooks
npm run test:hooks

Best practices

• JSON safety: Always use python3 json.dumps() for output — never string interpolation
• Fast execution: Keep hooks under their timeout; check tool availability with command -v
• No network calls: Hooks should be fast and local
• Path safety: Use realpath and verify paths are within the repository
• Error handling: Use set -euo pipefail; handle missing tools gracefully

Troubleshooting

Hook Not Firing

1. Verify the hook directory is listed in chat.hookFilesLocations in .vscode/settings.json
2. Check the script exists and the configured command uses bash: ls -la .github/hooks/{name}/{name}.sh
3. View hook output: Output panel → GitHub Copilot Chat Hooks channel

Hook Timeout

If a hook exceeds its timeout, VS Code kills the process and continues. Check for:

• Network calls in hooks (avoid — hooks should be fast and local)
• Large file processing
• Missing tool binaries (hooks should check command -v before running tools)

Manual Testing

Test a hook locally by piping mock JSON:

echo '{"tool_name":"run_in_terminal","tool_input":{"command":"ls"}}' | \
  bash .github/hooks/block-dangerous-commands/block-dangerous-commands.sh

Relationship to Git Hooks

Agent hooks (.github/hooks/) and git hooks (lefthook.yml) serve different purposes:

	Agent Hooks	Git Hooks (lefthook)
When	During agent sessions	On git commit/push
Scope	Individual tool invocations	Staged/changed files
Config	.github/hooks/*/hooks.json	lefthook.yml
Purpose	Real-time quality enforcement	Pre-commit/pre-push validation

Both systems complement each other — agent hooks catch issues during authoring, git hooks catch issues before commit.

Related

• Quickstart — install and run your first project
• Workflow — how agents collaborate across steps
• Troubleshooting — diagnose failed deploys