Fix agent-customization hooks reference: correct field names and PostToolUse format

[Copilot]

The built-in agent-customization skill's hooks reference (copilot-skill:/agent-customization/references/hooks.md) had incorrect field names and output formats, causing agents to generate hooks that silently failed.

Issues Fixed

Wrong field naming: Documentation didn't specify snake_case convention. Agents defaulted to camelCase (toolName, toolInput) but VS Code contract requires snake_case (tool_name, tool_input, tool_use_id).

Incomplete PostToolUse documentation: Missing input field list and output format. No mention of tool_response field.

Wrong output format: Documentation implied systemMessage for PostToolUse, but VS Code ignores this. Correct format is hookSpecificOutput.additionalContext.

Missing tool name mapping: No documentation of what tool_name values VS Code emits (e.g., Edit, Read, Bash), forcing agents to guess.

Changes

Added explicit snake_case convention (line 55)

**IMPORTANT:** All field names use **snake_case** (e.g., `tool_name`, `tool_input`, `tool_use_id`), not camelCase.

Added PostToolUse input/output documentation (lines 92-115)

Input fields:

• tool_name, tool_input, tool_use_id, tool_response

Output format:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Filtered result: ..."
  }
}

Added common tool names section (lines 124-132)

Lists 14 tool names by category: File Operations (Read, Edit, MultiEdit, Write, NotebookEdit), Search (Glob, Grep, LS), Execution (Bash, BashOutput, KillBash, Task), Network (WebFetch, WebSearch), Planning (EnterPlanMode, ExitPlanMode, TodoWrite), User Interaction (AskUserQuestion).

Added common input fields section (lines 57-64)

Documents timestamp, hookEventName, sessionId, transcript_path, cwd fields present in all hook events.

All field names and formats verified against hookCommandTypes.ts, chatHookService.ts, and ClaudeToolNames enum.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Agent-customization skill: hooks reference uses wrong field names and output format</issue_title>
<issue_description>## Problem

The built-in agent-customization skill's hooks reference (copilot-skill:/agent-customization/references/hooks.md) provides inaccurate field names and output format for hook input/output, which causes agents to generate broken hooks that silently fail.

Wrong input field names

The skill reference shows the PreToolUse example output using hookSpecificOutput correctly, but the common output format section only mentions systemMessage — which is not the documented way to inject context into PostToolUse responses.

More importantly, the reference does not clarify the hook input field naming convention. Agents generating hooks from this reference default to camelCase (toolName, toolInput), but the actual VS Code hook contract uses snake_case:

Skill reference (inferred)	Actual VS Code contract
toolName	tool_name
toolInput	tool_input
toolUseId	tool_use_id

Wrong PostToolUse output format

The skill reference's common output section suggests using:

{ "systemMessage": "..." }

But the official docs show that PostToolUse should use:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "..."
  }
}

Missing tool name mapping

The reference does not document what tool_name values VS Code sends for common operations (e.g., editFiles, createFile). Without this, agents guess tool names and filters silently miss events.

Impact

When an agent creates a PostToolUse hook following the skill reference:

1. The script parses toolName from stdin → gets empty string → skips all events
2. Even if the script runs, it outputs systemMessage → VS Code ignores it (wrong format)
3. The hook appears to work (exit code 0) but has no effect — silent failure

Suggestion

Update copilot-skill:/agent-customization/references/hooks.md to:

1. Show a complete PostToolUse input example with tool_name, tool_input, tool_use_id, tool_response, and cwd fields (snake_case)
2. Show the correct PostToolUse output using hookSpecificOutput.additionalContext
3. List common tool_name values that VS Code emits (e.g., editFiles, createFile, runTerminalCommand)
4. Add a note that field names use snake_case throughout, not camelCase

Reproduction

1. Ask Copilot agent mode to create a PostToolUse hook using the agent-customization skill
2. The generated script will use camelCase field names and systemMessage output
3. The hook silently does nothing when triggered

Environment

• VS Code Insiders
• Copilot Chat extension
• Agent mode with hooks enabled</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Agent-customization skill: hooks reference uses wrong field names and output format vscode#296189

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[digitarald]

@copilot Is this change very different from https://github.com/microsoft/vscode-copilot-chat/pull/3843/changes?

[Copilot]

@copilot Is this change very different from https://github.com/microsoft/vscode-copilot-chat/pull/3843/changes?

No, this is the same PR - both point to commit 9b56e52. The branches copilot/fix-agent-customization-hooks and PR #3843 are identical.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/graphql
  • Triggering command: /usr/bin/gh gh pr view 3843 --json title,body,files (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)