One-Line Summary: Hooks are user-defined scripts that fire on harness lifecycle events — before a tool runs, after it returns, when a session starts, when the agent stops — letting you add policy, logging, validation, or transformation without forking the harness.
Prerequisites: What is an AI harness, agent loop, tool use, function calling
Status: Module 02 anchor concept — first draft. Authoring backlog: bespoke
WalkthroughAHOHooksAndLifecycleEventsinteractive component (Phase D, see plan file).
What Are Hooks and Lifecycle Events?
Every harness exposes an internal sequence of events: a session is starting, a user prompt arrived, the model wants to call a tool, the tool returned, the agent decided to stop. Hooks are the user-supplied scripts that run at those moments. They are the harness's plugin point for behavior that cannot reasonably live in the model — blocking dangerous shell commands, scrubbing secrets from outputs, appending lint warnings to the conversation, kicking off a background audit, mirroring every action to a log.
Hooks are distinct from tools. A tool is something the model decides to call; a hook fires whether the model wants it to or not. They are also distinct from middleware in a web sense: hooks run on the local machine with the user's privileges, can mutate the in-flight tool call, and are observable to the model only insofar as the harness chooses to surface them.
How It Works
A harness defines a fixed vocabulary of events. Claude Code's published set includes SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, and Notification. Ruflo extends this surface to 27 events to support its swarm and federation semantics. The user registers a hook by adding an entry in settings.json (or the equivalent) that points to an executable — a shell script, a Node program, a Python file. When the event fires, the harness invokes the executable, passes context as JSON on stdin, and reads the response on stdout. The response can permit, deny, or rewrite the operation.
Why It Matters
Hooks are how every meaningful policy gets attached to a harness. Permission systems are hooks. Logging is hooks. PII redaction is hooks. Pre-commit checks before letting the agent push are hooks. Without hooks, every team would be forking the harness or wrapping it in a shell — an obvious nonstarter.
How Harnesses & Frameworks Implement This
| Harness / Framework | Hook surface | Configuration | Notes |
|---|---|---|---|
| Claude Code | SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, Notification | settings.json hooks field | Each hook is an executable invoked with JSON on stdin. |
| Claude Agent SDK | Programmatic hook registration | TypeScript/Python decorators or callbacks | Same lifecycle events as Claude Code, exposed as code. |
| ruflo | 27 lifecycle events | Plugin-declared, marketplace-distributed | Powers ruflo-core, ruflo-aidefence, ruflo-loop-workers. |
| LangGraph | Pre/post node callbacks via compile(checkpointer=...) and interrupts | Code-level | Closer to graph instrumentation than harness hooks. |
| AutoGen | register_reply / register_hook on agents | Python | Per-agent rather than per-harness. |
| CrewAI | Task callbacks (callback=...) and tool wrappers | Python | Limited surface compared to Claude Code. |
| OpenAI Agents SDK | Guardrails (input_guardrails, output_guardrails), lifecycle callbacks | Python/TypeScript | Guardrails are a specialized hook subset. |
| Codex CLI | Approval mode + sandbox policy | CLI flags + config | Less programmable than Claude Code's hooks. |
| Cursor | Limited — mainly via rules files | .cursorrules | Closer to a system prompt than a true hook. |
Connections to Other Concepts
what-is-an-ai-harness.md— Hooks are a load-bearing reason the harness is a distinct layer.slash-commands.md— Slash commands trigger user-driven entry points; hooks fire on system events.permission-and-tool-scoping-primitives.md— Most permission systems are implemented asPreToolUsehooks.prompt-injection-defense-in-harnesses.md— Defense-in-depth here is hook-based.background-worker-pattern.md—SessionStarthooks are the canonical worker trigger.
Further Reading
- Anthropic, "Claude Code Hooks Reference" — The canonical event vocabulary.
- ruvnet, ruflo USERGUIDE — Documents the 27-event extended hook surface.