Hooks and Lifecycle Events¶
Hooks enforce agent behavior mechanically. System prompts offer advisory guidance that models interpret flexibly. Hooks intercept agent actions at specific points and apply deterministic rules.
Enforcement¶
System prompts and instructions are probabilistic. They influence model behavior but cannot guarantee it. A model might misinterpret instructions, overlook constraints buried in long context, or prioritize being helpful over following safety guidelines.
Hooks address this by moving enforcement from the prompt layer to the execution layer. Instead of telling the model "don't write to /etc", a hook can block any write attempt to that path regardless of what the model decided.
Instructions vs Mechanics¶
| Aspect | Instructions | Hooks |
|---|---|---|
| Enforcement | Advisory (model interprets) | Mechanical (code enforces) |
| Reliability | Probabilistic | Deterministic |
| Visibility | Part of context window | Outside model awareness |
| Flexibility | Can be reasoned about | Cannot be circumvented |
| Overhead | Token cost | Execution cost |
Both have their place. Instructions guide reasoning and preferences. Hooks enforce invariants and safety boundaries.
Lifecycle¶
Every agent session follows a predictable lifecycle. Actions occur at identifiable moments that can be intercepted:
SessionStart
│
├── UserPromptSubmit ────────────────────┐
│ │ │
│ ├── PreToolUse (read) → PostToolUse │ Request/Response
│ ├── PreToolUse (edit) → PostToolUse │ Cycle
│ ├── PreToolUse (bash) → PostToolUse │
│ │ │
│ └── Response ────────────────────────┘
│
├── UserPromptSubmit ...
│
SessionEnd
Each lifecycle event is a control point where external logic can observe, modify, or block the action.
Event Categories¶
Lifecycle events fall into three categories based on what they control:
| Category | Events | Purpose |
|---|---|---|
| Session | SessionStart, SessionEnd | Setup and teardown, logging boundaries |
| Input | UserPromptSubmit, PermissionRequest | Intercept human-agent communication |
| Tool | PreToolUse, PostToolUse | Control individual agent actions |
Tool events have the finest granularity. A single user request might trigger dozens of tool calls, each passing through PreToolUse and PostToolUse events.
Hooks vs Plugins¶
Different runtimes use different terminology. Claude Code has "hooks", Opencode has "plugins". While the mechanisms differ, the concepts overlap:
| Aspect | Claude Code Hooks | Opencode Plugins |
|---|---|---|
| Mechanism | External commands | Go code or external commands |
| State | Stateless (fresh process each invocation) | Can maintain state across invocations |
| Configuration | JSON in settings | TOML configuration files |
| Scope | Project or user level | Project level |
| Communication | JSON on stdin/stdout | Plugin protocol |
The conceptual model - intercepting lifecycle events to apply deterministic rules - remains consistent across both.
Topics¶
- Event Model - The complete event taxonomy and what information is available at each point
- Patterns - Common patterns for gates, observers, and enforcement strategies