Fix hooks reference: correct field names and PostToolUse output format

[Copilot]

The agent-customization skill's hooks reference used incorrect field naming conventions and output format, causing agents to generate hooks that parse empty tool names and output ignored fields—resulting in silent failures.

Changes

Clarified snake_case convention

• Added prominent note that hook input fields use tool_name, tool_input, tool_use_id (not camelCase)
• Documented all input fields: tool_name, tool_input, tool_use_id, cwd, tool_response

Fixed PostToolUse output format

• Corrected from { "systemMessage": "..." } (ignored by VS Code)
• To { "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "..." } }

Added common tool names

• Documented 20+ tool_name values organized by category
• File Operations: Edit, MultiEdit, Write, Read, NotebookEdit
• Execution: Bash, BashOutput, KillBash, Task
• Code Search: Grep, Glob, LS
• Special: EnterPlanMode, ExitPlanMode, WebFetch, WebSearch, etc.

Added complete examples

Before (incomplete, wrong field names):

// Missing snake_case guidance, no tool_name example

After (complete input/output):

// PreToolUse Input
{
  "tool_name": "Bash",
  "tool_input": { "command": "npm install", "mode": "sync" },
  "tool_use_id": "toolu_01abc123",
  "cwd": "/workspace/project"
}

// PostToolUse Output
{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Tool completed successfully."
  }
}

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

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.