diff --git a/assets/prompts/skills/agent-customization/references/hooks.md b/assets/prompts/skills/agent-customization/references/hooks.md
index e373659f46..d6290631e2 100644
--- a/assets/prompts/skills/agent-customization/references/hooks.md
+++ b/assets/prompts/skills/agent-customization/references/hooks.md
@@ -52,22 +52,85 @@ Each hook command supports:
 
 Hooks receive JSON on stdin and can return JSON on stdout.
 
-- Common output: `continue`, `stopReason`, `systemMessage`
-- `PreToolUse` permissions are read from `hookSpecificOutput.permissionDecision` (`allow` | `ask` | `deny`)
-- `PostToolUse` output can block further processing with `decision: block`
+**IMPORTANT:** All field names use **snake_case** (e.g., `tool_name`, `tool_input`, `tool_use_id`), not camelCase.
 
-`PreToolUse` example output:
+### Common Input Fields
 
+All hook events receive these common fields:
+- `timestamp` (string): ISO 8601 timestamp
+- `hookEventName` (string): Event type (e.g., "PreToolUse", "PostToolUse")
+- `sessionId` (string, optional): Session identifier
+- `transcript_path` (string, optional): Path to session transcript file
+- `cwd` (string, optional): Working directory for the hook command
+
+### PreToolUse Hook
+
+**Input fields:**
+- `tool_name` (string): Name of the tool being invoked
+- `tool_input` (object): Tool input parameters
+- `tool_use_id` (string): Unique identifier for this tool invocation
+
+**Output format:**
 ```json
 {
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
     "permissionDecision": "ask",
-    "permissionDecisionReason": "Needs user confirmation"
+    "permissionDecisionReason": "Needs user confirmation",
+    "updatedInput": { ... },
+    "additionalContext": "Extra context for the agent"
+  }
+}
+```
+
+Fields in `hookSpecificOutput`:
+- `permissionDecision`: `allow` | `ask` | `deny` (controls tool execution)
+- `permissionDecisionReason`: Human-readable explanation
+- `updatedInput`: Modified tool input to use instead
+- `additionalContext`: Extra context injected into agent's prompt
+
+### PostToolUse Hook
+
+**Input fields:**
+- `tool_name` (string): Name of the tool that was invoked
+- `tool_input` (object): Tool input parameters
+- `tool_use_id` (string): Unique identifier for this tool invocation
+- `tool_response` (string): The output returned by the tool
+
+**Output format:**
+```json
+{
+  "decision": "block",
+  "reason": "Tool output violates policy",
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Filtered result: ..."
   }
 }
 ```
 
+Fields in output:
+- `decision`: Set to `"block"` to prevent tool result from reaching the agent
+- `reason`: Human-readable explanation for blocking
+- `hookSpecificOutput.additionalContext`: Context injected into agent's prompt (replaces or augments tool response)
+
+### Common Output Fields
+
+All hook types support:
+- `continue` (boolean): Set to `false` to stop processing remaining hooks
+- `stopReason` (string): Message to display when stopping execution
+- `systemMessage` (string): Warning message shown to user (deprecated for PostToolUse, use `additionalContext` instead)
+
+### Common Tool Names
+
+Common `tool_name` values VS Code emits:
+- **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`
+
 Exit codes:
 - `0` success
 - `2` blocking error