Agent frontmatter hooks

Agent frontmatter hooks are middleware directives scoped to an agent definition that fire in forked execution contexts, whereas skill-level hooks fire only in the main thread.

How They Work

Agent hooks are defined in .claude/agents/{name}.md frontmatter under a hooks key. Each hook specifies a trigger event (currently PreToolUse, PostToolUse, Stop), a tool matcher, and a command to execute. When an agent runs in any context, including forked subagent runs, its hooks traverse with the agent and fire according to the matched conditions.

hooks:
  PostToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: "echo 'AGENT-HOOK-FIRED' >> /tmp/agent-hook-log.txt"

The Critical Distinction: Forks

A runtime test (2026-01-07) compared hook fire behaviour across skill-level and agent-level definitions. When a skill invoked an agent in a forked context, skill hooks did not fire, but agent hooks did. This creates a hard rule: agent hooks are portable middleware; skill hooks are main-thread-only middleware.

The test defined hooked-researcher with a PostToolUse hook on Read, created a skill that used this agent with context: fork, and verified the hook fired by observing a log file written during forked execution.

Why It Matters

Forked workflows need access to instrumentation. Logging, audit trails, validation before tool calls, and side effects that must run regardless of execution context now have a natural primitive. Agent hooks solve a scope problem: you cannot attach main-thread-only middleware to code that runs elsewhere.

Caveats

• Hooks defined at skill level do not cross fork boundaries
• Hook fire depends on tool matcher precision; a Read matcher fires only on Read tools
• Command hooks execute synchronously; the result does not block the tool call