Agent frontmatter hooks — runtime test
Hands-on runtime battle-test of Agent frontmatter hooks. Result: PASS.
Agent-level hooks in frontmatter fire in forked contexts, unlike skill-level hooks, making them portable middleware for distributed agent workflows.
Setup and Test
A test agent, hooked-researcher, was defined with a PostToolUse hook in its .claude/agents/hooked-researcher.md frontmatter. The hook was configured to fire after any Read tool invocation and execute a shell command that logged "AGENT-HOOK-FIRED" to a file. A skill was then created that explicitly delegated to this agent in a forked context, and the test was executed on 2026-01-07.
Result
PASS. The hook fired and the log file was created, even though the skill ran in a forked context where main-thread hooks do not execute. This was the critical finding: agent frontmatter hooks persist across context boundaries.
Key Distinction
Hooks bind at different scopes with different lifecycle semantics:
| Hook Location | Fires in Fork? | Scope |
|---|---|---|
| Skill frontmatter | NO | Main thread only |
| Agent frontmatter | YES | Travels with agent |
When a skill delegates to a subagent or fork, skill-level hooks are left in the parent context and do not fire in child processes. Agent-level hooks, by contrast, are bundled into the agent definition itself and execute wherever the agent runs.
Implications for Distributed Workflows
Because agent hooks survive context forks, they serve as portable middleware: logging, validation, and side effects can be attached to the agent and guaranteed to fire regardless of execution context. This enables patterns like audit trails in forked validators, pre-tool guardrails in delegated subagents, and context-independent instrumentation without threading hooks through the skill layer.
Skill hooks remain the appropriate choice for main-thread observability and orchestration control; agent hooks are the primitive for agent-internal guarantees.
Test Results: Hooks in Agent Frontmatter
Feature: Added hooks support to agent frontmatter, allowing agents to define PreToolUse, PostToolUse, and Stop hooks scoped to the agent's lifecycle
Tested: 2026-01-07
Test Setup
Created .claude/agents/hooked-researcher.md:
---
name: hooked-researcher
tools: Read, Grep, Glob
model: haiku
hooks:
PostToolUse:
- matcher: "Read"
hooks:
- type: command
command: "echo 'AGENT-HOOK-FIRED' >> /tmp/agent-hook-log.txt"
---
Created skill using this agent:
---
agent: hooked-researcher
context: fork
---
Test Result
Result: PASS
- Log file created with "AGENT-HOOK-FIRED"
- Hook fired even though skill ran in forked context
Key Finding
Agent hooks vs Skill hooks:
| Hook Location | Fires in Fork? |
|---|---|
| Skill frontmatter | NO |
| Agent frontmatter | YES |
This is a critical distinction:
- Skill hooks are tied to the main thread
- Agent hooks travel with the agent into forked contexts
Implications
- For forked workflows that need hooks, use agent-level hooks
- Agent hooks = portable middleware
- Skill hooks = main-thread-only middleware
Use Cases for Agent Hooks
- Logging/audit in forked contexts
- Validation before tool use in subagents
- Side effects that should happen regardless of fork
Status: PASS
Agent frontmatter hooks work and fire in forked contexts (unlike skill hooks).
test_33addd917bf7eb178bd08cc9ed255199b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd950c1e4732ef7afdccbc7195aa255945b40a9015308a778e7b18c8f6641a380739f01e46e27bf3f5c30a2b5d159c512065d88217422431b02e5947d3b722e701Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.
- verifies Agent frontmatter hooks Primitive