Hooks Core Reference

Claude Code Hooks — Core Reference (May 2026)

Hooks execute custom commands, HTTP calls, MCP tool calls, LLM prompts, or agent verifiers in response to Claude Code events. Use for automation, validation, formatting, and security.

For JSON input/output schemas, activate Skill(skill: "plugin-creator:hooks-io-api"). For working examples and patterns, activate Skill(skill: "plugin-creator:hooks-patterns").

All Hook Events

Stop vs SubagentStop — scope distinction

Stop fires in every session — the main orchestrator session and inside embedded subagents (Agent-tool spawned). When firing inside a subagent, the input includes agent_id and agent_type fields. Use these to guard hooks that should only run in the main session:

// Only run in the main orchestrator, not inside embedded subagents
if (data.agent_id || data.agent_type) {
    process.stdout.write(JSON.stringify({}));
    process.exit(0);
}

SubagentStop fires only in the parent session when an Agent-tool call completes.

Frontmatter exception: Stop hooks defined in skill/agent frontmatter are automatically converted to SubagentStop for that component's lifecycle. This only applies to frontmatter-defined hooks, not plugin or settings hooks.

Configuration

Configuration Locations

Enterprise administrators can use allowManagedHooksOnly to block user, project, and plugin hooks. Hooks from plugins force-enabled in managed enabledPlugins are exempt.

Structure

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

Hook Handler Fields

Common fields (all hook types):

Command hook fields (in addition to common):

HTTP hook fields:

Prompt/agent hook fields:

Event-Specific Matchers

PreToolUse / PermissionRequest / PostToolUse / PostToolUseFailure / PermissionDenied

Matched against tool_name. Matcher rules:

• Plain name: Write matches only Write tool
• Pipe list: Edit|Write matches either
• Regex (contains non-alphanumeric chars): ^Notebook or mcp__memory__.*
• mcp__<server>__.* matches all tools from a server (.* required — bare mcp__server is exact match, finds nothing)

SubagentStart / SubagentStop

Matched against agent_type. For custom subagents, agent_type is the name field from the agent's frontmatter, not the filename.

SessionStart

SessionEnd

Notification

InstructionsLoaded

ConfigChange

PreCompact / PostCompact

Setup

StopFailure

Elicitation / ElicitationResult

Matched against the MCP server name.

UserPromptExpansion

Matched against command_name (the slash command name).

FileChanged

Matcher value is split on | and registered as literal filenames to watch (e.g. .envrc|.env). Same value also filters which hook groups run when a file changes.

No-matcher events

UserPromptSubmit, PostToolBatch, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, CwdChanged — matchers are silently ignored on these events. They always fire on every occurrence.

Path Placeholders

Use in command and args fields to reference scripts at stable paths:

Exec form (when args is set): Claude Code spawns the executable directly. Each args element is one argument with no shell tokenization. Use for paths that may contain spaces.

Shell form (when args is absent): command string passed to sh -c. Wrap placeholders in double-quotes.

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/my-hook.cjs"]
}

Environment Variables

CLAUDE_ENV_FILE — Persisting Environment Variables

Variables written to CLAUDE_ENV_FILE are sourced before each Bash command. Append (>>) to preserve variables set by other hooks.

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

Execution Details

Security Considerations

Command hooks run with your system user's full permissions and can modify, delete, or access any files your account can access.

Best practices:

1. Validate and sanitize inputs — never trust stdin data blindly
2. Quote shell variables — use "$VAR" not $VAR
3. Block path traversal — check for .. in file paths
4. Use ${CLAUDE_PROJECT_DIR} for absolute paths — never relative
5. Skip sensitive files — avoid .env, .git/, keys, etc.

Debugging

# Write debug log to file
claude --debug-file /tmp/claude.log

# Enable verbose mode mid-session
ctrl+O

Debug output shows which hooks matched, exit codes, and full stdout/stderr.

For more granular matcher details: CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose.

Troubleshooting

Test Commands Manually

echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' | ./your-hook.sh

Sources

• Hooks Reference (accessed 2026-05-21)
• Hooks Guide (accessed 2026-05-21)
• Settings Reference
• Plugin Components Reference