hooks.md +0 −100
295 295
296Recognizes the same matcher values as PreToolUse.296Recognizes the same matcher values as PreToolUse.
297 297
298### PostCustomToolCall
299
300Runs after an MCP tool completes but **before** `PostToolUse` hooks execute. This hook allows you to modify the tool's output before it's processed further or shown to the model.
301
302**Key characteristics:**
303
304* **Only runs for MCP tools** (tools starting with `mcp__`)
305* Executes after the tool completes but before `PostToolUse` hooks
306* Can modify tool output using the `updatedOutput` field
307* Original tool response is replaced with modified output
308
309**Common use cases:**
310
311* Adding metadata to MCP tool responses
312* Filtering sensitive information from tool outputs
313* Transforming response formats
314* Logging MCP tool usage with enriched data
315
316**Important**: If multiple hooks provide `updatedOutput` for the same tool call, they may conflict. Hook execution order is non-deterministic when hooks run in parallel. Only configure one hook per tool to modify output.
317
318**Matchers:**
319Recognizes the same matcher values as PreToolUse, but will only execute for MCP tools (`mcp__*`).
320
321### Notification298### Notification
322 299
323Runs when Claude Code sends notifications. Notifications are sent when:300Runs when Claude Code sends notifications. Notifications are sent when:
482}459}
483```460```
484 461
485### PostCustomToolCall Input
486
487The exact schema for `tool_input` and `tool_response` depends on the MCP tool.
488
489```json theme={null}
490{
491 "session_id": "abc123",
492 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
493 "cwd": "/Users/...",
494 "permission_mode": "default",
495 "hook_event_name": "PostCustomToolCall",
496 "tool_name": "mcp__github__create_issue",
497 "tool_input": {
498 "title": "Bug report",
499 "body": "Description of the issue"
500 },
501 "tool_response": {
502 "issue_number": 42,
503 "url": "https://github.com/org/repo/issues/42"
504 }
505}
506```
507
508### Notification Input462### Notification Input
509 463
510```json theme={null}464```json theme={null}
713}667}
714```668```
715 669
716#### `PostCustomToolCall` Output Control
717
718`PostCustomToolCall` hooks can modify MCP tool outputs before they're processed further.
719
720* `"hookSpecificOutput.updatedOutput"` replaces the original tool response
721* The modified output is shown to Claude instead of the original response
722* This runs **before** `PostToolUse` hooks, so they see the modified output
723
724```json theme={null}
725{
726 "hookSpecificOutput": {
727 "hookEventName": "PostCustomToolCall",
728 "updatedOutput": {
729 "issue_number": 42,
730 "url": "https://github.com/org/repo/issues/42",
731 "hook_processed": true,
732 "processed_at": "2025-01-01T00:00:00Z"
733 }
734 }
735}
736```
737
738**Example: Adding metadata to MCP tool responses**
739
740```bash theme={null}
741#!/bin/bash
742# Read JSON input from stdin
743INPUT=$(cat)
744
745# Extract tool information
746TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
747TOOL_RESPONSE=$(echo "$INPUT" | jq -r '.tool_response')
748
749# Only process MCP tools
750if [[ "$TOOL_NAME" != mcp__* ]]; then
751 exit 0
752fi
753
754# Add metadata to the response
755UPDATED_OUTPUT=$(echo "$TOOL_RESPONSE" | jq '. + {"hook_processed": true, "processed_at": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}')
756
757# Output the modified response
758jq -n --argjson output "$UPDATED_OUTPUT" '{
759 "hookSpecificOutput": {
760 "hookEventName": "PostCustomToolCall",
761 "updatedOutput": $output
762 }
763}'
764```
765
766<Warning>
767 If multiple hooks provide `updatedOutput` for the same tool call, conflicts may occur since hooks run in parallel. Only configure one hook per tool to modify output.
768</Warning>
769
770#### `UserPromptSubmit` Decision Control670#### `UserPromptSubmit` Decision Control
771 671
772`UserPromptSubmit` hooks can control whether a user prompt is processed.672`UserPromptSubmit` hooks can control whether a user prompt is processed.