claude-hooks-reference-2026

Complete reference for Claude Code hooks system (January 2026). Use when creating hooks, understanding hook events, matchers, exit codes, JSON output control, environment variables, plugin hooks, or implementing hook scripts.

Ir para a instalação

Repositório: diegosouzapw/awesome-omni-skill
Última atividade na origem: 28 de fevereiro de 2026 às 18:11
Idioma detectado do SKILL.md: inglês
Estrelas: 50
Forks: 19

Opções de instalação

Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.

npx skills add https://github.com/diegosouzapw/awesome-omni-skill --skill claude-hooks-reference-2026

O comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.

Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.

Revise os arquivos de origem

Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.

Explorador de arquivos

2 arquivos

SKILL.md

Instruções da origem · Visualização somente leitura

Voltar à pesquisa Voltar à instalação

artifact-tracking

Token-efficient tracking for AI orchestration. CLI-first for status updates (~50 tokens), agent fallback for complex ops (~1KB). Use when: updating task status, querying blockers, creating progress files, validating phases.

2026-03-02

ash-ai

AshAi extension guidelines for integrating AI capabilities with Ash Framework. Use when implementing vectorization/embeddings, exposing Ash actions as LLM tools, creating prompt-backed actions, or setting up MCP servers. Covers semantic search, LangChain integration, and structured outputs.

2026-03-02

ask-oracle

This skill should be used when solving hard questions, complex architectural problems, or debugging issues that benefit from GPT-5 Pro or GPT-5.1 thinking models with large file context. Use when standard Claude analysis needs deeper reasoning or extended context windows.

2026-03-02

Ver todas deste repositório

Stop

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

{
  "name": "my-plugin",
  "hooks": "./hooks/hooks.json"
}

{
  "name": "my-plugin",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

---
name: code-reviewer
description: Review code changes
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/one-time-setup.sh"
          once: true

Matcher	Description
`Task`	Subagent tasks
`Bash`	Shell commands
`Glob`	File pattern matching
`Grep`	Content search
`Read`	File reading
`Edit`	File editing
`Write`	File writing
`WebFetch`	Web fetching
`WebSearch`	Web search
`Notebook.*`	NotebookEdit, NotebookRead
`mcp__<server>__.*`	All tools from MCP server
`mcp__.__write.`	MCP write tools across servers

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "psql -c 'SELECT * FROM users'",
    "description": "Query the users table",
    "timeout": 120000
  },
  "tool_use_id": "toolu_01ABC123"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  },
  "tool_use_id": "toolu_01ABC123"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission to use Bash",
  "notification_type": "permission_prompt"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate factorial"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_transcript_path": "/path/to/subagents/agent-def456.jsonl"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "Setup",
  "trigger": "init"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup",
  "model": "claude-sonnet-4-20250514"
}

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

Event	Exit Code 2 Behavior
`PreToolUse`	Blocks tool call, shows stderr to Claude
`PermissionRequest`	Denies permission, shows stderr to Claude
`PostToolUse`	Shows stderr to Claude (tool already ran)
`PostToolUseFailure`	Shows stderr to Claude (tool already failed)
`Notification`	Shows stderr to user only
`UserPromptSubmit`	Blocks prompt, erases it, shows stderr to user
`Stop`	Blocks stoppage, shows stderr to Claude
`SubagentStart`	Shows stderr to user only
`SubagentStop`	Blocks stoppage, shows stderr to Claude subagent
`PreCompact`	Shows stderr to user only
`Setup`	Shows stderr to user only
`SessionStart`	Shows stderr to user only
`SessionEnd`	Shows stderr to user only

{
  "continue": true,
  "stopReason": "Message shown when continue is false",
  "suppressOutput": false,
  "systemMessage": "Optional warning message shown to user"
}

Field	Type	Effect
`continue`	boolean	`false` stops Claude (takes precedence over all)
`stopReason`	string	Shown to user when `continue` is false
`suppressOutput`	boolean	Hide stdout from transcript mode
`systemMessage`	string	Warning message shown to user

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved documentation file",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

Field	Values	Effect
`permissionDecision`	`allow`, `deny`, `ask`	Controls tool execution
`permissionDecisionReason`	string	Shown to user (allow/ask) or Claude (deny)
`updatedInput`	object	Modifies tool input before execution
`additionalContext`	string	Added to Claude's context

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Command not allowed by policy",
      "interrupt": true
    }
  }
}

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

{
  "decision": "block",
  "reason": "Prompt contains sensitive data",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

{
  "hookSpecificOutput": {
    "hookEventName": "Setup",
    "additionalContext": "Repository initialized with custom configuration"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project context loaded successfully"
  }
}

{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete.",
  "timeout": 30
}

{
  "ok": true,
  "reason": "Explanation for the decision"
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if this subagent should stop. Input: $ARGUMENTS\n\nCheck if:\n- The subagent completed its assigned task\n- Any errors occurred that need fixing\n- Additional context gathering is needed\n\nReturn: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"explanation\"} to continue."
          }
        ]
      }
    ]
  }
}

Event	Use Case
`Stop`	Intelligent task completion detection
`SubagentStop`	Verify subagent completed task
`UserPromptSubmit`	Context-aware prompt validation
`PreToolUse`	Complex permission decisions
`PermissionRequest`	Intelligent allow/deny dialogs

Feature	Command Hooks	Prompt Hooks
Execution	Runs bash script	Queries LLM
Decision logic	You implement in code	LLM evaluates context
Setup complexity	Requires script file	Configure prompt only
Context awareness	Limited to script	Natural language understanding
Performance	Fast (local)	Slower (API call)
Use case	Deterministic rules	Context-aware decisions

Variable	Description	Available In
`CLAUDE_PROJECT_DIR`	Project root (absolute path)	All hooks
`CLAUDE_CODE_REMOTE`	`"true"` if remote, empty if local	All hooks
`CLAUDE_ENV_FILE`	Path for persisting env vars	SessionStart, Setup
`CLAUDE_PLUGIN_ROOT`	Plugin directory (absolute)	Plugin hooks

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi
exit 0

#!/bin/bash
ENV_BEFORE=$(export -p | sort)

# Run setup commands that modify environment
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

Aspect	Behavior
Timeout	60 seconds default, configurable
Parallelization	All matching hooks run in parallel
Deduplication	Identical commands deduplicated
Environment	Runs in cwd with Claude Code's env
Hook order	Hooks from all sources execute together

Event	stdout Handling
UserPromptSubmit, SessionStart, Setup	Added to Claude's context
PreToolUse, PostToolUse, Stop	Shown in verbose mode (Ctrl+O)
Notification, SessionEnd, SubagentStart	Logged to debug only (`--debug`)

claude --debug
claude --debug "hooks"  # Filter to hooks only

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

Problem	Cause	Fix
Hook not running	Wrong matcher pattern	Check case-sensitivity, regex
Command not found	Relative path	Use `$CLAUDE_PROJECT_DIR`
JSON not processed	Non-zero exit code	Exit 0 for JSON processing
Hook times out	Slow script	Optimize or increase timeout
Quotes breaking	Unescaped in JSON	Use `\"` inside JSON strings
Plugin hook not load	Invalid plugin.json hooks config	Validate with `claude plugin validate .`
Path not found	Missing `${CLAUDE_PLUGIN_ROOT}`	Use variable for plugin scripts

# CLI (from terminal)
claude plugin validate .
claude plugin validate ./path/to/plugin

# In Claude Code session
/plugin validate .
/plugin validate ./path/to/plugin

python3 -m json.tool .claude/settings.json

echo '{"tool_name":"Write","tool_input":{"file_path":"test.txt"}}' | ./your-hook.sh

#!/usr/bin/env python3
import json
import re
import sys

# Define validation rules as (regex pattern, message) tuples
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files -g pattern' instead of 'find -name'",
    ),
]

def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues

try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(0)

issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Exit code 2 blocks tool call and shows stderr to Claude
    sys.exit(2)

#!/usr/bin/env python3
import json
import sys
import re
import datetime

try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Check for sensitive patterns
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Use JSON output to block with a specific reason
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Add current time to context
context = f"Current time: {datetime.datetime.now()}"
print(context)

# Equivalent JSON approach:
# print(json.dumps({
#   "hookSpecificOutput": {
#     "hookEventName": "UserPromptSubmit",
#     "additionalContext": context,
#   },
# }))

sys.exit(0)

#!/usr/bin/env python3
import json
import sys

try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Auto-approve file reads for documentation files
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        output = {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "allow",
                "permissionDecisionReason": "Documentation file auto-approved"
            },
            "suppressOutput": True
        }
        print(json.dumps(output))
        sys.exit(0)

# Let normal permission flow proceed
sys.exit(0)

#!/usr/bin/env node

const output = {
  hookSpecificOutput: {
    hookEventName: "SessionStart",
    additionalContext: `<project-context>
Environment: ${process.env.NODE_ENV || "development"}
Node version: ${process.version}
Working directory: ${process.cwd()}
</project-context>`,
  },
};

console.log(JSON.stringify(output));

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_PROJECT_DIR\"/**/*.{js,ts,json}"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/check-protected-files.sh"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Verify task completion. Check edge cases. Return {\"ok\": true} or {\"ok\": false, \"reason\": \"...\"}."
          }
        ]
      }
    ]
  }
}

Event	When Fired	Matcher Applies	Common Uses
`PreToolUse`	Before tool execution	Yes	Validation, blocking
`PermissionRequest`	When user shown permission dialog	Yes	Auto-approval policies
`PostToolUse`	After successful tool execution	Yes	Formatting, linting
`PostToolUseFailure`	After tool fails	Yes	Error handling
`Notification`	When Claude wants attention	Yes	Custom notifications
`UserPromptSubmit`	User submits prompt	No	Input validation

Event	When Fired	Matcher Applies	Common Uses
`PreToolUse`	Before tool execution	Yes	Validation, blocking
`PermissionRequest`	When user shown permission dialog	Yes	Auto-approval policies
`PostToolUse`	After successful tool execution	Yes	Formatting, linting
`PostToolUseFailure`	After tool fails	Yes	Error handling
`Notification`	When Claude wants attention	Yes	Custom notifications
`UserPromptSubmit`	User submits prompt	No	Input validation

Matcher	Trigger
`startup`	New session started
`resume`	`--resume`, `--continue`, or `/resume`
`clear`	`/clear` command
`compact`	Auto or manual compact

Matcher	Trigger
`manual`	`/compact` command
`auto`	Auto-compact (full context)

Matcher	Trigger
`init`	`--init` or `--init-only` flags
`maintenance`	`--maintenance` flag

name	claude-hooks-reference-2026
description	Complete reference for Claude Code hooks system (January 2026). Use when creating hooks, understanding hook events, matchers, exit codes, JSON output control, environment variables, plugin hooks, or implementing hook scripts.
user-invocable	true

Matcher	Trigger
`permission_prompt`	Permission requests from Claude
`idle_prompt`	Claude waiting for input (60s+ idle)
`auth_success`	Authentication success
`elicitation_dialog`	MCP tool elicitation

Tool	Fields
`Bash`	`command`, `description`, `timeout`, `run_in_background`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`, `replace_all`
`Read`	`file_path`, `offset`, `limit`

Code	Behavior
0	Success. stdout processed (JSON or plain text)
2	Blocking error. stderr used as error message, fed back to Claude
Other	Non-blocking error. stderr shown in verbose mode (Ctrl+O)

Field	Required	Description
`type`	Yes	`"prompt"` for LLM evaluation, `"agent"` for tools
`prompt`	Yes	Prompt text sent to LLM
`timeout`	No	Seconds (default: 30 for prompt, 60 for agent)

Field	Type	Description
`ok`	boolean	`true` allows the action, `false` prevents it
`reason`	string	Required when `ok` is `false`. Shown to Claude

claude-hooks-reference-2026

Informações da origem

Opções de instalação

Revise os arquivos de origem

Mais deste repositório

Claude Code Hooks System - Complete Reference (January 2026)

All Hook Events

Mais deste repositório

Claude Code Hooks System - Complete Reference (January 2026)

All Hook Events

Configuration

Configuration Locations (Precedence highest to lowest)

Structure

Project-Specific Hook Scripts

Events Without Matchers

Plugin Hooks

How Plugin Hooks Work

Plugin Hook Configuration

Plugin Environment Variables

Hooks in Skills, Agents, and Slash Commands

Skill Example

Agent Example

once Option

Event-Specific Matchers

PreToolUse / PermissionRequest / PostToolUse Common Matchers

SessionStart Matchers

PreCompact Matchers

Setup Matchers

Notification Matchers

Hook Input (JSON via stdin)

Common Fields (All Events)

PreToolUse Input

PostToolUse Input

Notification Input

UserPromptSubmit Input

Stop Input

SubagentStart Input

SubagentStop Input

PreCompact Input

Setup Input

SessionStart Input

SessionEnd Input

Hook Output

Exit Codes

Exit Code 2 Behavior Per Event

JSON Output Control

Common JSON Fields (All Events)

PreToolUse JSON Output

PermissionRequest JSON Output

PostToolUse JSON Output

UserPromptSubmit JSON Output

Stop / SubagentStop JSON Output

Setup JSON Output

SessionStart JSON Output

Prompt-Based Hooks

How Prompt-Based Hooks Work

Configuration

Response Schema

$ARGUMENTS Placeholder

Example: Intelligent Stop Hook

Example: SubagentStop Validation

Best Use Cases

Comparison with Command Hooks

Best Practices for Prompt Hooks

Important Hook Events

Setup Hook

SessionStart Hook

PostToolUseFailure Hook

SubagentStart Hook

Environment Variables

SessionStart Environment Persistence

Working with MCP Tools

MCP Tool Naming

Configuring Hooks for MCP Tools

Execution Details

Output Handling by Event

Security Considerations

Disclaimer

Security Best Practices

Configuration Safety

`once` Option