How do the top AI agent harnesses handle hooks?
Six of the seven harnesses document a way to run your own code before a tool call and block it; Antigravity documents lifecycle hooks in its SDK. Where they differ is failure: in Claude Code, Codex and Cursor a hook that errors lets the action proceed unless it is set to fail closed. Read 2026-11-06.
Contents
Short answer, from the docs read: a hook is the same idea everywhere, your code running at a fixed point in the agent loop, and six of the seven document a point before a tool call; Antigravity's documented hooks run around a turn and on tool errors. Claude Code, Codex and Cursor take a command that reads JSON on stdin and signals a block with an exit code or a JSON decision.[1][2][3] OpenCode and pi take code in a plugin or extension file.[4][5] Hermes Agent has four separate hook systems.[6] Antigravity documents lifecycle hooks in its SDK as Python decorators.[7] The sharpest difference is what a failing hook does: Claude Code, Codex and Cursor let the action go ahead when a hook crashes or times out, unless the hook is set to fail closed.[1][2][3] This is the fourth page in a series that began with a survey of the harnesses, then memory and tool calls.
Where a hook attaches
- Claude Code lists 33 events, among them SessionStart and SessionEnd, UserPromptSubmit, Stop, PreToolUse, PostToolUse, PermissionRequest, SubagentStart, PreCompact and a set for worktrees, tasks and model switches. A handler can be a shell command, an HTTP call, an MCP tool, a prompt sent to a model, or an agent that checks a condition; the agent type is marked experimental.[1]
- Codex documents events including SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, SubagentStart and Stop. Hooks go in hooks.json or a [hooks] table in config.toml, at the user or the repository level, or ship inside a plugin. PreToolUse and PostToolUse cover shell and MCP calls and most local function tools.[2]
- Cursor lists events including beforeShellExecution, beforeMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preToolUse, postToolUse, sessionStart, sessionEnd, subagentStart, preCompact and stop. Hooks are spawned processes that talk JSON over stdio, defined in hooks.json at the project or user level or installed through plugins.[3]
- OpenCode hooks are plugins: JavaScript or TypeScript files in .opencode/plugins/ or ~/.config/opencode/plugins/, or npm packages. The events include tool.execute.before, tool.execute.after, permission.asked, session.created, session.compacted and session.idle.[4]
- pi hooks are extensions that register handlers with pi.on. The tool sequence is tool_execution_start, tool_call, tool_execution_update, tool_result and tool_execution_end; other events include session_start, before_agent_start and agent_end.[5]
- Hermes Agent has four systems: gateway event hooks (a HOOK.yaml and a handler.py in a hooks directory, firing only in the messaging gateway), plugin hooks registered in Python such as pre_tool_call, post_tool_call, pre_llm_call and on_session_start, shell hooks, and outbound webhooks.[6]
- Antigravity documents SDK lifecycle hooks as decorators, for example one that runs before a turn and returns allow or deny, and one for tool errors. Its overview page lists "Lifecycle Hooks" under extensibility.[7][8]
Which hooks can block
- Claude Code. A command hook that exits 2 stops the action on events that can block. JSON output can also deny.[1]
- Codex. A supported hook blocks by returning an explicit denial. Background hooks cannot block, approve or rewrite the operation, so the docs say to use synchronous hooks for tool policies and permission decisions.[2]
- Cursor. Exit code 2 blocks the action, the same as returning permission "deny".[3]
- OpenCode. The documented example, ".env protection", throws an error from tool.execute.before when a read targets an .env file.[4] Another example in the same docs rewrites a bash command's arguments.[4]
- pi. The tool_call event can block or mutate input, and tool_result can change the result.[5]
- Hermes Agent. A shell pre_tool_call hook can block or fail closed. When several plugin directives disagree, block beats approve, which beats no directive.[6]
- Antigravity. The SDK example returns a result with allow set to true or false.[7]
What happens when a hook fails
- Claude Code. An exit code other than 0 or 2, or a hook that does not start or prints invalid JSON, is a non-blocking error and the action goes ahead, except for hooks configured with onFailure set to block.[1]
- Codex. A PreToolUse error, timeout or malformed response can let the tool run. Errors, missing servers and unavailable tools do not block an MCP tool hook.[2]
- Cursor. Invalid JSON or a response that does not match the schema blocks the action. Crashes, timeouts and exit codes other than 2 are "fail open by default": Cursor logs the failure and lets the action through. A failClosed option exists for hooks defined in files.[3]
- Hermes Agent. Callback errors are logged and skipped. A plugin callback on a timeout-bounded hook that runs past the limit, 30 seconds by default, is abandoned so the agent loop continues.[6]
- OpenCode, pi and Antigravity. The pages read did not say.
Who can add a hook and who has to approve it
- Codex requires non-managed hooks to be reviewed and trusted before they run, loads project-local hooks only when the project's .codex layer is trusted, and has a managed layer set from a requirements file.[2]
- Hermes Agent treats gateway hooks as trusted by placement: dropping the two files into the hooks directory is the opt-in.[6]
- Claude Code has a /hooks menu and a documented way to turn hooks off for a run.[1]
- Cursor has enterprise, team and project hook sources and a setting to block until they load.[3]
What the comparison rules out
These are consequences of the docs read, not findings from a test.
- A hook is not a guarantee by itself. In the three harnesses that document failure behavior in detail, a hook that crashes or times out can let the action through unless it is set to fail closed. A rule that must always hold needs a hook set to fail closed, or a sandbox.
- "Supports hooks" hides a split in kind: shell commands that read JSON (Claude Code, Codex, Cursor) against code loaded into the harness (OpenCode, pi, Hermes Agent plugins, Antigravity's SDK). The second kind runs inside the agent's own process, so a bug in it can affect the agent; the docs read do not test this.
- Event counts do not compare. Claude Code lists 33; the others document fewer in the pages read, which may reflect page structure and not the real number of events.
Terms
- Hook: your code that the harness runs at a fixed point, such as before a tool call.
- Fail open and fail closed: whether the action goes ahead (open) or is stopped (closed) when the hook itself breaks.
- Matcher: a pattern that limits a hook to certain tools or commands.
- Tool call: a request from the model to run one of the harness's tools.
Not yet proven
- Whether hooks hold under attack. No source read tests a bypass.
- Failure behavior of OpenCode, pi and Antigravity hooks. Not stated in the pages read.
- The full event lists. The pages read for Codex, Cursor, OpenCode and pi were skimmed for names, not counted.
- Hermes Agent's shell hooks and outbound webhooks. Named but not described here.
- Antigravity's CLI hooks. Only the SDK page and the overview mention are cited.
- Currency. All pages were read on 2026-11-06; hook names change between versions.
If you rely on a hook to stop an action and it failed open on you, I would like to hear it: mackenzie@mackenziebowes.com.
Sources
- Claude Code Docs, Hooks reference. Read in Rotunda 2026-11-06. code.
claude. com/ docs/ en/ hooks - OpenAI, Codex docs, Hooks. Read in Rotunda 2026-11-06. learn.
chatgpt. com/ docs/ hooks - Cursor Docs, Hooks. Read in Rotunda 2026-11-06. cursor.
com/ docs/ hooks - OpenCode docs, Plugins. Read in Rotunda 2026-11-06. opencode.
ai/ docs/ plugins/ - Pi docs, Extensions. Read in Rotunda 2026-11-06. pi.
dev/ docs/ latest/ extensions - Hermes Agent docs, Event Hooks. Read in Rotunda 2026-11-06. hermes-
agent. nousresearch. com/ docs/ user- guide/ features/ hooks - Google Antigravity Docs, Lifecycle hooks, triggers and session persistence. Read in Rotunda 2026-11-06. antigravity.
google/ docs/ sdk/ lifecycle/ - Google Antigravity Docs, overview. Read in Rotunda 2026-11-06. antigravity.
google/ docs/ overview/
Terms on this page
- Hook: A command that an AI coding agent runs automatically at a set point in its work.
- Model Context Protocol: An open standard for connecting AI applications to outside tools and data.
- Tool call: A request from an AI model to run one action, such as a search or a file write, which the surrounding program carries out.