Harness Notes

decide

The first handler answering yes or no wins; only user-level and -e extensions can answer.

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.

add context · stop

add context · set environment

Only command and mcp_tool handlers run, and mcp_tool is skipped at launch.

add context · set environment

Fire-and-forget; continue:false does not block session creation.

in source, not in docs

observe only

observe only

load extra resources

Returns extra skill, prompt and theme paths, accumulated across handlers.

load extra resources

Returns pluginPaths to load; fires on every workspace folder change.

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.

set environment

No matcher. Variables written to CLAUDE_ENV_FILE are cleared at the next CwdChanged.

block

Changes to policy settings cannot be blocked.

in source, not in docs

observe only

delegate

Provider operation: the hook creates the worktree and returns its path (command hooks on stdout, HTTP hooks in hookSpecificOutput.worktreePath).

in source, not in docs

observe only

in source, not in docs

observe only

delegate

Provider operation: the hook performs removal; this is not a notification hook.

Fires only for worktrees a WorktreeCreate hook created.

modify · replace

Setting result supplies the title.

in source, not in docs

observe only

in source, not in docs

observe only

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

cancel

cancel · modify

Besides cancelling, can only skip conversation restore.

in source, not in docs

observe only

cancel · replace · modify

observe only

in source, not in docs

observe only

observe only

Main thread only; advisory and always synchronous.

observe only

observe only

observe only

Fires on quit, reload, new, resume and fork.

in source, not in docs

observe only

in source, not in docs

observe only

block · add context

block · add context

block · add context

block

Cursor's 2.4 changelog mentions modifying prompts, but the hooks reference documents no output field for it.

modify · block

Throwing stops prompt admission.

modify · take over

Transforms chain; handled short-circuits.

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

add context · modify · replace

Returning systemPrompt replaces the whole system prompt. Since 1.2.0 also fires for triggered extension messages.

in source, not in docs

observe only

observe only

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

observe only

observe only

block

block · stop

observe only

block · stop

retry · decide

Overrides the retry decision for a provider failure.

in source, not in docs

observe only

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.

in source, not in docs

observe only

observe only

in source, not in docs

observe only

queue follow-up · stop

decision: "block" queues a continuation prompt; continue: false from any hook takes precedence.

block · add context

queue follow-up

loop_limit caps follow-ups (default 5).

add context · queue follow-up

The last point at which a handler can append entries and request one more provider call.

add context · queue follow-up

Can append entries and request one more provider call.

in source, not in docs

observe only

observe only

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

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.

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".

allow · deny · modify

ask is accepted by the schema but not enforced for preToolUse.

modify · block

Throwing blocks the tool.

block · modify

Mutating event.input patches arguments without re-validation. The first block wins; a thrown error blocks the tool.

in source, not in docs

observe only

observe only

in source, not in docs

observe only

observe only

observe only

modify

Receives completed or error status.

modify

Handlers compose; each sees earlier changes.

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.

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.

add context · modify

Output can be replaced only for MCP tools.

in source, not in docs

observe only

add context

add context

Also fires on timeouts and permission denials.

in source, not in docs

observe only

add context · stop

allow · deny

Any deny wins. updatedInput, updatedPermissions and interrupt fail closed.

allow · deny · modify · update permissions · stop

Exit code 2 is not honoured; deny with decision.behavior. updatedInput applies only when allowing.

allow · deny · ask user · annotate

An explicitly configured deny is final and does not invoke the hook.

in source, not in docs

observe only

in source, not in docs

observe only

retry

Fires only in auto mode; retry is ignored for denials without a verdict.

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

replace · delegate · block

User ! and !! commands, not the agent's bash tool. The first handler to answer wins; a failure blocks the command.

allow · deny · ask user

modify · set environment

Can change the command, working directory, timeout, shell and environment.

in source, not in docs

observe only

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

allow · deny

allow · deny

Tab completions only, not the agent.

observe only

observe only

Tab completions only, not the agent.

set environment

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

take over

Handling it makes the extension responsible for connecting registered servers.

in source, not in docs

observe only

in source, not in docs

observe only

allow · deny · ask user

Cursor recommends failClosed: true for security-critical MCP hooks.

observe only

take over · deny · cancel

modify · deny · cancel

add context

add context

allow · deny

ask is treated as deny.

queue follow-up · stop

block · add context

queue follow-up

The follow-up is used only when the subagent completed.

observe only

in source, not in docs

observe only

modify

System prompt, messages, tools and options for agent requests.

modify

modify · replace

Runs after every context handler, on the full transcript including system messages.

decide

Returns warm or stop; the last handler that answers wins.

stop

continue: false ends the turn before compacting.

block

observe only

Cannot block or modify compaction; can show a message to the user.

modify · replace

Setting result skips the model call.

in source, not in docs

observe only

cancel · replace

in source, not in docs

observe only

stop

continue: false ends the turn after compacting.

observe only

in source, not in docs

observe only

observe only

in source, not in docs

observe only

observe only

in source, not in docs

observe only

observe only

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.

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.

observe only

modify

Headers and raw settings; can be scoped to one provider.

modify

modify · replace

modify · replace

modify

Experimental.

modify

Experimental.

in source, not in docs

replace

Supplies the AI SDK provider instance.

in source, not in docs

replace

Supplies the language model instance.

replace

Each returned payload replaces the request and is passed to the next handler.

observe only

Handlers are awaited in stream order, so a slow handler delays the stream.

modify · replace

modify

Experimental.

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

observe only

in source, not in docs

observe only

replace

The replacement must keep the message role.

modify

displayContent changes only what is shown on screen; the transcript and what Claude sees keep the original.

observe only

Pi starts waiting on a blocking extension prompt.

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

observe only

in source, not in docs

modify

in source, not in docs

modify

in source, not in docs

modify

in source, not in docs

modify

in source, not in docs

modify

modify

modify

in source, not in docs

modify

in source, not in docs

modify

in source, not in docs

modify

in source, not in docs

modify

in source, not in docs

modify