/hone

Claude Code Hook System Reference

Purpose: Read this when selecting a hook event, deciding between prompt and command, editing settings.json, or validating hook I/O and lifecycle rules.

Contents

• Configuration formats
• Event catalog
• Hook types
• Matcher patterns
• Input format
• Output format
• Environment variables
• Lifecycle constraints

Configuration Formats

Hone primarily manages the end-user settings.json format.

settings.json Shape

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/validate-bash.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Structure rules:

• hooks lives at the top level.
• Each event key maps to an array of matcher groups.
• Each matcher group has matcher plus hooks.
• Each hook has type, command or prompt, and optional timeout.

Event Catalog

Full 26-event lifecycle table (timing, block-capable, hook-type support, primary use) → reference/hooks/event-catalog.md. Always consult it before choosing an event.

Event-Specific Contracts

PreToolUse Blocking Example

{
  "hookSpecificOutput": {
    "permissionDecision": "allow|deny|ask",
    "updatedInput": {"field": "modified_value"}
  },
  "systemMessage": "Explanation for Claude"
}

Stop / SubagentStop Blocking Example

{
  "decision": "approve|block",
  "reason": "Explanation",
  "systemMessage": "Additional context"
}

Hook Types

prompt

{
  "type": "prompt",
  "prompt": "Evaluate whether this tool use is appropriate: $TOOL_INPUT",
  "timeout": 30
}

Use prompt for context-aware decisions, policy checks, and nuanced validation. It is supported only on PreToolUse, PostToolUse, UserPromptSubmit, Stop, and SubagentStop.

command

{
  "type": "command",
  "command": "bash /path/to/script.sh",
  "timeout": 60
}

Use command for fast deterministic checks, file operations, external tools, and all command-only events.

Matcher Patterns

Common examples:

Matchers are case-sensitive.

Input Format

All hooks receive JSON on stdin with common fields:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.txt",
  "cwd": "/current/working/dir",
  "permission_mode": "ask|allow",
  "hook_event_name": "PreToolUse"
}

Output Format

Standard Output

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "Message for Claude"
}

Output fields:

• continue: halt processing if false
• suppressOutput: hide output from transcript if true
• systemMessage: message injected into Claude's context

Exit Codes

Environment Variables

SessionStart can persist environment variables with:

echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"

Lifecycle Constraints

Load and Restart

• Hooks load only at session start.
• Editing hook configuration does not affect the current session.
• After changes: edit -> restart Claude Code -> verify with /hooks.

Parallelism

• Matching hooks inside the same matcher group run in parallel.
• Hooks do not see each other's output.
• Ordering is non-deterministic.
• Design hooks to be independent.

Startup Validation

• Invalid JSON prevents loading.
• Missing scripts cause warnings.
• Syntax errors surface in claude --debug.
• Use /hooks to confirm the active configuration.

Timeout Defaults

• prompt: 30s
• command: 60s
• Production hooks should still set explicit timeout values.

Hook Contract (full)

Canonical detail for the Hook Contract summarized in SKILL.md.

Hook Types

Selection guidance: Start with command hooks for formatting and linting, graduate to prompt hooks for security and policy decisions, use agent hooks only for deep verification requiring tool access. Prefer command for latency-sensitive paths (target ≤ 200ms per hook). Use http for external audit trails and webhook integrations. Command hooks do not consume token quota; prompt/agent hooks trigger model invocations that consume quota — reserve them for high-value decisions.

When multiple hooks on the same event return different decisions, the strictest wins: deny > defer > ask > allow for PreToolUse; deny > allow for PermissionRequest. Identical command hooks (same command string) or HTTP hooks (same URL) matched by multiple matchers are deduplicated and run only once.

Exit Codes

Hook output injected into context is capped at 10,000 characters; excess is saved to a file with a preview and path.

Matcher Patterns

Matchers are case-sensitive: "write" does not match "Write".

settings.json Structure

settings.json
└── hooks
    └── Event[]
        └── { matcher, hooks[] }
            └── { type, prompt|command, timeout }

Structure rules:

• Edit only the top-level hooks section.
• Each event key maps to an array of matcher groups.
• Each matcher group contains one matcher string plus a hooks array.
• Hooks inside the same matcher group run in parallel.
• Validate with jq . ~/.claude/settings.json before finishing.

Hook sources (merged at runtime): ~/.claude/settings.json (user), .claude/settings.json (project shared), .claude/settings.local.json (project local), managed policy settings (org-wide), plugin hooks/hooks.json (when enabled), skill/agent frontmatter (component lifetime). Hooks defined in skill/agent frontmatter are scoped to the component's lifetime and auto-cleaned up. Enterprise policy allowManagedHooksOnly: true blocks all non-managed hooks. disableAllHooks: true disables all hooks at the same or lower settings level.

Common Hook Fields

Command Hook Rules

• Read stdin exactly once.
• On exit 2, write blocking JSON to stderr, not stdout.
• On exit 0, optional JSON to stdout is safe.
• Use set -uo pipefail; avoid set -e.
• Use PID-scoped temp files such as /tmp/hook-state-$$.
• Set explicit timeouts even when defaults would apply.

Model-Based Gate Design

When a hook's decision cannot be expressed as a pattern (security / quarantine recipes reaching for an LLM judgment), copy the shipped auto-mode architecture rather than inventing one. Source: anthropic.com/engineering/claude-code-auto-mode (2026-03-25), measured FPR 0.4% on 10,000 real actions, FNR 17% on real overeager actions and 5.7% on synthetic exfiltration.

Timing rule (quarantine). Project-local config — .claude/settings.json, including its hooks block — must not be parsed until after the user's trust prompt is answered. Anthropic shipped this inverted and a repo could execute hook commands pre-consent. Any hook or tool that reads untrusted repo config inherits this ordering requirement. Related ordering bug: resolve symlinks first, then validate containment — "symlink resolution has to happen before path validation, not after, or a symlink inside an authorized folder can point outside and escape" (anthropic.com/engineering/how-we-contain-claude).

Scope limit. A hook is a model-layer control and never the sole defense. Environment controls (sandbox, egress policy) catch what a classifier misses: prompt-injection success is ~0.1% single-shot but 5-6% under 100 adaptive attempts, and when the user is the one typing the hostile prompt, no intent-anchored classifier fires at all (credentials exfiltrated 24/25 times in Anthropic's own phishing test). Recommend sandboxing alongside any security hook — it independently removed 84% of permission prompts.

Signal Keywords -> Recipe (full table)

For natural-language input without an explicit subcommand. Subcommand match wins if both apply. Signals not in the Recipes table map to a workflow focus or reference rather than a Recipe.