Hooks

Updated 2026-10-21

On this page

Which moments a hook can attach to, and what it can do there. Event names link to each harness’s documentation. “Block”, “deny” and “modify” change what the agent does; “observe only” can watch but not intervene. Where hook files live is on the Locations page.

Moment	Codex CLIHook commands	Claude CodeHook commands	Cursor AgentHook commands	OpenCode 2.xPlugin hooks and events	piExtension event handlers
Hook types	command mcp_tool prompt (accepted but skipped) agent (accepted but skipped)	command http mcp_tool prompt agent (experimental)	command prompt	Plugin hooks and events	Extension event handlers
Session and workspace
Project trust is decided	—	—	—	—	`project_trust` decide The first handler answering yes or no wins; only user-level and -e extensions can answer.
Session setup	—	`Setup` set environment Fires only with --init-only, or --init/--maintenance in -p mode; JSON output, including additionalContext, is discarded. Only command and mcp_tool handlers run, and mcp_tool is skipped.	—	—	—
Session starts	`SessionStart` add context, stop	`SessionStart` add context, set environment Only command and mcp_tool handlers run, and mcp_tool is skipped at launch.	`sessionStart` add context, set environment Fire-and-forget; continue:false does not block session creation.	`session.created` undocumented observe only	`session_start` observe only
Resources are discovered	—	—	—	—	`resources_discover` load extra resources Returns extra skill, prompt and theme paths, accumulated across handlers.
Workspace opens	—	—	`workspaceOpen` load extra resources Returns pluginPaths to load; fires on every workspace folder change.	—	—
Directory is added	—	`DirectoryAdded` add context For /add-dir the hook's systemMessage reaches Claude as context on the next turn; for repository-root registration it only reaches the debug log.	—	—	—
Working directory changes	—	`CwdChanged` set environment No matcher. Variables written to CLAUDE_ENV_FILE are cleared at the next CwdChanged.	—	—	—
Configuration changes	—	`ConfigChange` block Changes to policy settings cannot be blocked.	—	`config.updated` undocumented observe only	—
Worktree is created	—	`WorktreeCreate` delegate Provider operation: the hook creates the worktree and returns its path (command hooks on stdout, HTTP hooks in hookSpecificOutput.worktreePath).	—	—	—
Worktree is resolved	—	—	—	`worktree.resolved` undocumented observe only	—
Worktree updates	—	—	—	`worktree.updated` undocumented observe only	—
Worktree is removed	—	`WorktreeRemove` delegate Provider operation: the hook performs removal; this is not a notification hook. Fires only for worktrees a WorktreeCreate hook created. The 2.1.301 changelog reports a fix for exit removing hook-created worktrees without confirmation despite possible unpushed commits. Other WorktreeRemove cases may still remove without asking.	—	—	—
Session details change	—	—	—	`session.title` modify, replace Setting result supplies the title. `session.renamed` undocumented observe only `session.metadata.updated` undocumented observe only	`session_info_changed` observe only
Session status changes	—	—	—	`session.status` undocumented observe only	—
Session is viewed	—	—	—	`session.viewed` undocumented observe only	—
Session is moved	—	—	—	`session.moved` undocumented observe only	—
Session goes idle	—	—	—	`session.idle` undocumented observe only	—
Before switching sessions	—	—	—	—	`session_before_switch` cancel
Before forking a session	—	—	—	—	`session_before_fork` cancel, modify Besides cancelling, can only skip conversation restore.
Session is forked	—	—	—	`session.forked` undocumented observe only	—
Before navigating the session tree	—	—	—	—	`session_before_tree` cancel, replace, modify
After navigating the session tree	—	—	—	—	`session_tree` observe only
Session is deleted	—	—	—	`session.deleted` undocumented observe only	—
Session ends	`SessionEnd` observe only Main thread only; advisory and always synchronous.	`SessionEnd` observe only	`sessionEnd` observe only	—	`session_shutdown` observe only Fires on quit, reload, new, resume and fork.
Server connects	—	—	—	`server.connected` undocumented observe only	—
Server shuts down	—	—	—	`location.shutdown` undocumented observe only	—
Prompt and turn
Before a prompt or command is expanded	—	`UserPromptExpansion` block, add context	—	—	—
User submits a prompt	`UserPromptSubmit` block, add context	`UserPromptSubmit` block, add context	`beforeSubmitPrompt` block Cursor's 2.4 changelog mentions modifying prompts, but the hooks reference documents no output field for it.	`session.prompt` modify, block Throwing stops prompt admission.	`input` modify, take over Transforms chain; handled short-circuits.
Message is queued	—	—	—	`session.inbox.enqueued` undocumented observe only	—
Queued message delivery changes	—	—	—	`session.inbox.delivery.changed` undocumented observe only	—
Queued message is delivered	—	—	—	`session.inbox.delivered` undocumented observe only	—
Queued message is cancelled	—	—	—	`session.inbox.cancelled` undocumented observe only	—
Agent is selected	—	—	—	`session.agent.selected` undocumented observe only	—
Before the agent starts	—	—	—	—	`before_agent_start` add context, modify, replace Returning systemPrompt replaces the whole system prompt. Since 1.2.0 also fires for triggered extension messages.
Agent starts	—	—	—	`session.execution.started` undocumented observe only	`agent_start` observe only
Turn starts	—	—	—	—	`turn_start` observe only
Model step starts	—	—	—	`session.step.started` undocumented observe only	—
Model step streams	—	—	—	`session.step.streamed` undocumented observe only	—
Model step ends	—	—	—	`session.step.ended` undocumented observe only	—
Model step fails	—	—	—	`session.step.failed` undocumented observe only	—
Skill is activated	—	—	—	`session.skill.activated` undocumented observe only	—
After the agent thinks	—	—	`afterAgentThought` observe only	—	—
After the agent responds	—	—	`afterAgentResponse` observe only	—	—
Task is created	—	`TaskCreated` block	—	—	—
Task is completed	—	`TaskCompleted` block, stop	—	—	—
Notification is sent	—	`Notification` observe only	—	—	—
Teammate goes idle	—	`TeammateIdle` block, stop	—	—	—
Turn is retried	—	—	—	`session.retry` retry, decide Overrides the retry decision for a provider failure. `session.retry.scheduled` undocumented observe only	—
Turn is interrupted	`Interrupt` observe only Runs when you interrupt an active turn on the main thread; not for subagents. The matcher is ignored. Can only emit a system message; it cannot prevent or reverse the interruption.	—	—	`session.execution.interrupted` undocumented observe only	—
Turn fails	—	`StopFailure` observe only	—	`session.execution.failed` undocumented observe only	—
Agent finishes its turn	`Stop` queue follow-up, stop decision: "block" queues a continuation prompt; continue: false from any hook takes precedence.	`Stop` block, add context	`stop` queue follow-up loop_limit caps follow-ups (default 5).	—	`agent_before_settle` add context, queue follow-up The last point at which a handler can append entries and request one more provider call.
Turn ends	—	—	—	—	`turn_end` add context, queue follow-up Can append entries and request one more provider call.
Agent ends	—	—	—	`session.execution.succeeded` undocumented observe only	`agent_end` observe only
Agent settles	—	—	—	—	`agent_settled` observe only
Tools
Tool input starts streaming	—	—	—	`session.tool.input.started` undocumented observe only	—
Tool input streams	—	—	—	`session.tool.input.delta` undocumented observe only	—
Tool input is complete	—	—	—	`session.tool.input.ended` undocumented observe only	—
Before a tool runs	`PreToolUse` deny, modify, add context permissionDecision ask, and allow without updatedInput, fail the hook run; the tool call proceeds. Covers shell, apply_patch, MCP and local function tools, not hosted tools such as web search.	`PreToolUse` allow, deny, ask user, defer, modify, add context defer works only in -p mode and for a single tool call per turn. A hook that times out does not block unless the handler sets onFailure: "block".	`preToolUse` allow, deny, modify ask is accepted by the schema but not enforced for preToolUse.	`tool.execute.before` modify, block Throwing blocks the tool.	`tool_call` block, modify Mutating event.input patches arguments without re-validation. The first block wins; a thrown error blocks the tool.
Tool execution starts	—	—	—	`session.tool.called` undocumented observe only	`tool_execution_start` observe only
Tool execution reports progress	—	—	—	`session.tool.progress` undocumented observe only	`tool_execution_update` observe only
Tool execution ends	—	—	—	—	`tool_execution_end` observe only
After a tool runs (any result)	—	—	—	`tool.execute.after` modify Receives completed or error status.	`tool_result` modify Handlers compose; each sees earlier changes.
After a tool succeeds	`PostToolUse` replace, add context decision: "block" or continue: false replaces the tool result with the feedback and continues; side effects are not undone. Also runs after shell commands that exit non-zero.	`PostToolUse` add context, modify, annotate decision: "block" does not undo the tool; it adds the reason next to the result. updatedToolOutput and updatedMCPToolOutput replace the output Claude sees.	`postToolUse` add context, modify Output can be replaced only for MCP tools.	`session.tool.success` undocumented observe only	—
After a tool fails	—	`PostToolUseFailure` add context	`postToolUseFailure` add context Also fires on timeouts and permission denials.	`session.tool.failed` undocumented observe only	—
After a batch of tools	—	`PostToolBatch` add context, stop	—	—	—
Permissions and questions
Permission is requested	`PermissionRequest` allow, deny Any deny wins. updatedInput, updatedPermissions and interrupt fail closed.	`PermissionRequest` allow, deny, modify, update permissions, stop Exit code 2 is not honoured; deny with decision.behavior. updatedInput applies only when allowing.	—	`permission.evaluate` allow, deny, ask user, annotate An explicitly configured deny is final and does not invoke the hook. `permission.asked` undocumented observe only	—
Permission is answered	—	—	—	`permission.replied` undocumented observe only	—
Permission is denied	—	`PermissionDenied` retry Fires only in auto mode; retry is ignored for denials without a verdict.	—	—	—
Session permissions change	—	—	—	`session.permissions` undocumented observe only	—
Form is shown to the user	—	—	—	`form.created` undocumented observe only	—
User submits a form	—	—	—	`form.replied` undocumented observe only	—
User cancels a form	—	—	—	`form.cancelled` undocumented observe only	—
Shell, terminals and files
User runs a shell command (!)	—	—	—	—	`user_bash` replace, delegate, block User ! and !! commands, not the agent's bash tool. The first handler to answer wins; a failure blocks the command.
Before a shell command	—	—	`beforeShellExecution` allow, deny, ask user	`shell.create.before` modify, set environment Can change the command, working directory, timeout, shell and environment.	—
Shell command starts	—	—	—	`session.shell.started` undocumented observe only	—
After a shell command	—	—	`afterShellExecution` observe only	`session.shell.ended` undocumented observe only	—
Background shell is created	—	—	—	`shell.created` undocumented observe only	—
Background shell exits	—	—	—	`shell.exited` undocumented observe only	—
Background shell is removed	—	—	—	`shell.deleted` undocumented observe only	—
Terminal is created	—	—	—	`pty.created` undocumented observe only	—
Terminal updates	—	—	—	`pty.updated` undocumented observe only	—
Terminal exits	—	—	—	`pty.exited` undocumented observe only	—
Terminal is removed	—	—	—	`pty.deleted` undocumented observe only	—
Persistent terminal is added	—	—	—	`persistent-pty.added` undocumented observe only	—
Persistent terminal is removed	—	—	—	`persistent-pty.removed` undocumented observe only	—
Before a file is read	—	—	`beforeReadFile` allow, deny	—	—
Before Tab reads a file	—	—	`beforeTabFileRead` allow, deny Tab completions only, not the agent.	—	—
After a file is edited	—	—	`afterFileEdit` observe only	—	—
After Tab edits a file	—	—	`afterTabFileEdit` observe only Tab completions only, not the agent.	—	—
Watched file changes	—	`FileChanged` set environment	—	`filesystem.changed` undocumented observe only	—
Revert is staged	—	—	—	`session.revert.staged` undocumented observe only	—
Revert is applied	—	—	—	`session.revert.committed` undocumented observe only	—
Staged revert is cleared	—	—	—	`session.revert.cleared` undocumented observe only	—
Git branch changes	—	—	—	`vcs.branch.updated` undocumented observe only	—
MCP
MCP servers are registered or removed	—	—	—	—	`mcp_servers_change` take over Handling it makes the extension responsible for connecting registered servers.
MCP server status changes	—	—	—	`mcp.status.changed` undocumented observe only	—
MCP resources change	—	—	—	`mcp.resources.changed` undocumented observe only	—
Before an MCP tool runs	—	—	`beforeMCPExecution` allow, deny, ask user Cursor recommends failClosed: true for security-critical MCP hooks.	—	—
After an MCP tool runs	—	—	`afterMCPExecution` observe only	—	—
MCP server asks the user	—	`Elicitation` take over, deny, cancel	—	—	—
User answers an MCP server	—	`ElicitationResult` modify, deny, cancel	—	—	—
Subagents
Subagent starts	`SubagentStart` add context	`SubagentStart` add context	`subagentStart` allow, deny ask is treated as deny.	—	—
Subagent finishes	`SubagentStop` queue follow-up, stop	`SubagentStop` block, add context	`subagentStop` queue follow-up The follow-up is used only when the subagent completed.	—	—
Context and compaction
Instructions are loaded	—	`InstructionsLoaded` observe only	—	`session.instructions.updated` undocumented observe only	—
Before context is sent to the model	—	—	—	`session.context` modify System prompt, messages, tools and options for agent requests.	`context` modify `context_with_system` modify, replace Runs after every context handler, on the full transcript including system messages.
Prompt cache warming is decided	—	—	—	—	`cache_warming_decision` decide Returns warm or stop; the last handler that answers wins.
Before context is compacted	`PreCompact` stop continue: false ends the turn before compacting.	`PreCompact` block	`preCompact` observe only Cannot block or modify compaction; can show a message to the user.	`session.compaction` modify, replace Setting result skips the model call. `session.compaction.started` undocumented observe only	`session_before_compact` cancel, replace
Compaction streams	—	—	—	`session.compaction.delta` undocumented observe only	—
After context is compacted	`PostCompact` stop continue: false ends the turn after compacting.	`PostCompact` observe only	—	`session.compaction.ended` undocumented observe only	`session_compact` observe only
Compaction fails	—	—	—	`session.compaction.failed` undocumented observe only	`session_compact_failed` observe only
Model and provider
Model is selected	—	—	—	`session.model.selected` undocumented observe only	`model_select` observe only
Before the model switches	—	`PreModelSwitch` allow, deny, ask user Runs only for switches a user or client requested (/model, the model picker, /config, fast mode, SDK set_model); automatic fallback and resume restores reach PostModelSwitch only. The matcher is compared against the canonical target model name; when no canonical name resolves, every PreModelSwitch hook runs regardless of matcher. A hook timeout blocks the switch, unlike PreToolUse. Outside interactive /model, ask is treated as a refusal.	—	—	—
After the model switches	—	`PostModelSwitch` add context Also runs for automatic fallback, opusplan plan-mode transitions, and model restoration on resume, but not for a one-turn fallback-chain substitution. Cannot block. Output is delivered with the next request; only the last switch's output is delivered when several switches precede that request.	—	—	—
Thinking level is selected	—	—	—	—	`thinking_level_select` observe only
Before provider headers are sent	—	—	—	`session.model.request` modify Headers and raw settings; can be scoped to one provider.	`before_provider_headers` modify
Before a provider request	—	—	—	`session.generate` modify, replace `session.http.request` modify, replace `session.experimental.ws.handshake` modify Experimental. `session.experimental.ws.send` modify Experimental. `aisdk.sdk` undocumented replace Supplies the AI SDK provider instance. `aisdk.language` undocumented replace Supplies the language model instance.	`before_provider_request` replace Each returned payload replaces the request and is passed to the next handler.
Provider streams a response	—	—	—	—	`provider_stream_event` observe only Handlers are awaited in stream order, so a slow handler delays the stream.
After a provider response	—	—	—	`session.http.response` modify, replace `session.experimental.ws.receive` modify Experimental.	`after_provider_response` observe only
Token usage updates	—	—	—	`session.usage.updated` undocumented observe only	—
Credentials change	—	—	—	`credential.updated` undocumented observe only	—
Active credential switches	—	—	—	`credential.switched` undocumented observe only	—
Provider list changes	—	—	—	`provider.updated` undocumented observe only	—
Model list changes	—	—	—	`model.updated` undocumented observe only	—
Model catalog refreshes	—	—	—	`models-dev.refreshed` undocumented observe only	—
Integration changes	—	—	—	`integration.updated` undocumented observe only	—
Messages and interface
Message starts	—	—	—	—	`message_start` observe only
Text starts streaming	—	—	—	`session.text.started` undocumented observe only	—
Text streams	—	—	—	`session.text.delta` undocumented observe only	—
Text is complete	—	—	—	`session.text.ended` undocumented observe only	—
Reasoning starts	—	—	—	`session.reasoning.started` undocumented observe only	—
Reasoning streams	—	—	—	`session.reasoning.delta` undocumented observe only	—
Reasoning ends	—	—	—	`session.reasoning.ended` undocumented observe only	—
Message updates	—	—	—	—	`message_update` observe only
Synthetic message is added	—	—	—	`session.synthetic` undocumented observe only	—
Message ends	—	—	—	—	`message_end` replace The replacement must keep the message role.
Message is displayed	—	`MessageDisplay` modify displayContent changes only what is shown on screen; the transcript and what Claude sees keep the original.	—	—	—
Extension prompt opens	—	—	—	—	`ui_prompt_start` observe only Pi starts waiting on a blocking extension prompt.
Extension prompt closes	—	—	—	—	`ui_prompt_end` observe only
Text is added to the prompt	—	—	—	`tui.prompt.append` undocumented observe only	—
Interface command runs	—	—	—	`tui.command.execute` undocumented observe only	—
Toast is shown	—	—	—	`tui.toast.show` undocumented observe only	—
Session is selected in the interface	—	—	—	`tui.session.select` undocumented observe only	—
Plugins and configuration
Plugin updates	—	—	—	`plugin.updated` undocumented observe only	—
Project updates	—	—	—	`project.updated` undocumented observe only	—
Agent list changes	—	—	—	`agent.updated` undocumented observe only	—
Command list changes	—	—	—	`command.updated` undocumented observe only	—
Skill list changes	—	—	—	`skill.updated` undocumented observe only	—
References change	—	—	—	`reference.updated` undocumented observe only	—
Web search settings change	—	—	—	`websearch.updated` undocumented observe only	—
Update is available	—	—	—	`installation.update-available` undocumented observe only	—
Installation updates	—	—	—	`installation.updated` undocumented observe only	—
Definitions a plugin can edit
Tool definitions	—	—	—	`tool.transform` undocumented modify	—
Agent definitions	—	—	—	`agent.transform` undocumented modify	—
Command definitions	—	—	—	`command.transform` undocumented modify	—
Skill definitions	—	—	—	`skill.transform` undocumented modify	—
MCP server definitions	—	—	—	`mcp.transform` undocumented modify	—
Provider definitions	—	—	—	`provider.transform` modify	—
Model definitions	—	—	—	`model.transform` modify	—
Integration definitions	—	—	—	`integration.transform` undocumented modify	—
Reference definitions	—	—	—	`reference.transform` undocumented modify	—
Web search definitions	—	—	—	`websearch.transform` undocumented modify	—
Worktree definitions	—	—	—	`worktree.transform` undocumented modify	—
Version control definitions	—	—	—	`vcs.transform` undocumented modify	—

Notes and sources

Codex CLI

Matching hooks are launched concurrently, so one hook cannot stop another from starting.
Project hooks load only in a trusted project, and every non-managed hook must also be reviewed and trusted by its hash.
Background (async) hooks cannot block, approve or rewrite the triggering operation.
OpenAI describes tool hooks as a guardrail, not a complete enforcement boundary.

Codex hooks, Documentation, checked 2026-10-15
Codex CLI 0.162.1 hook event names, Source code, checked 2026-10-14
Codex CLI 0.162.1 hook output parsing, Source code, checked 2026-10-14
Codex CLI 0.162.1 hook handler discovery, Source code, checked 2026-10-14

Claude Code

onFailure: "block" on a command or HTTP hook makes a failed or timed-out hook block the action (2.1.295 and later).
Plugin mods are a separate JavaScript hook surface with their own events and are not recorded here.
2.1.302 published changes: at most 12 prompt and agent hooks for one event run at once; remaining handlers wait. This is not the subagent concurrency limit or a stated cap on command/MCP hooks.
2.1.304 caps skill hooks from each source (a repository, personal folder or plugin) at 1,024 hooks and 16,384 matcher characters per session; these are separate from the 12 prompt/agent-hook concurrency limit.
2.1.304 fixes a skill once hook removing another skill’s identical hook, preserves a PreToolUse deny reason when an SDK callback hook times out, and excludes up to 10 minutes of SessionStart command-hook runtime from the VS Code subprocess initialization timeout.
2.1.304 adds a transcript notice identifying the event and plugin when an earlier plugin skips a mod hook. Mod tool.check gains e.isReadOnly and decider: person; settings.read receives individual layers and can rewrite merged settings. Mods remain a separate JavaScript hook surface.

Claude Code hooks reference, Documentation, checked 2026-10-15
Claude Code 2.1.301 published changes, Documentation, checked 2026-10-16
Claude Code 2.1.302 published changes; no runtime probe, Documentation, checked 2026-10-19
Claude Code 2.1.304 published changes; no runtime probe, Documentation, checked 2026-10-21

Cursor Agent

Permission hooks block when output is invalid JSON or does not match the schema; crashes, timeouts and other exit codes fail open unless the hook sets failClosed: true.
When several hooks answer, deny beats ask and ask beats allow.
Sources run in priority order enterprise, team, project, user; project hooks run only in trusted workspaces.
Cloud agents run only command hooks and skip sessionStart, sessionEnd, workspaceOpen, MCP and Tab hooks; no hooks run during early read-only turns.

Cursor hooks, Documentation, checked 2026-10-15

OpenCode 2.x

@opencode/cli 2.x, checked at 2.0.28. 1.x plugins do not run in 2.x.
Plugins register hooks per domain with ctx.<domain>.hook(name, callback); each callback receives one mutable event. Hooks run in plugin order.
Transforms are synchronous edits to registered definitions, replayed in registration order.
Events are read with ctx.event.subscribe() and can only be observed.
2.1 renames provider replay data to native across text/reasoning lifecycle, tool and step/compaction events. Tool result native shallow-merges into call native; execution state is unchanged. SessionCompactionResult.providerState becomes native. session.compacted is removed; subscribe to current compaction lifecycle events.
2.1 adds paginated ctx.session.list to both Effect and Promise plugin APIs.

OpenCode v2 plugin development, Documentation, checked 2026-10-15
OpenCode 2.0.29 session hooks, Source code, checked 2026-10-15
OpenCode 2.0.29 event union, Source code, checked 2026-10-15
OpenCode 2.1.0 official release notes; snapshot retained in October 21 review, Documentation, checked 2026-10-21
OpenCode v2.1.1: packages/schema/src/session-legacy.ts, Source code, checked 2026-10-21

In-process TypeScript extension events, run in extension load order; extensions run with full user permissions.
pi's documentation names its extension type definitions as the event reference.
Project extensions load only after the project is trusted.

pi 1.2.0 extension event overloads, Source code, checked 2026-10-14