Hook trigger reference

The complete lifecycle reference pulled out of the Agent Hooks lesson, so you can jump back to it mid-workshop. The lesson keeps the lifecycle diagram and the examples; this page holds the lookup tables.

Trigger reference

Trigger	Fires when	Matcher matches	Can block?
SessionStart	Session begins	None	No
Stop	Session ends	None	No
PreToolUse	Before a tool runs	Tool name (regex)	Yes
PostToolUse	After a tool runs	Tool name (regex)	No
PreTaskExec	Before a spec task starts	None	Yes
PostTaskExec	After a spec task finishes	None	No
UserPromptSubmit	You submit a prompt	Prompt text (regex)	Yes
PostFileCreate	After a file is created	File path (regex)	No
PostFileSave	After a file is saved	File path (regex)	No
PostFileDelete	After a file is deleted	File path (regex)	No
Manual	You trigger it on demand	None	No

`Stop` is once per session, not once per turn

Stop fires when the whole session ends, not after each agent turn. To react to each change the agent makes mid-session, use PostFileSave or PostToolUse instead.

Matcher semantics

matcher is a regex. What it’s tested against depends on the trigger:

Trigger	Matcher evaluates against
PostFileSave, PostFileCreate, PostFileDelete	File path
PreToolUse, PostToolUse	Tool name
UserPromptSubmit	Prompt text
SessionStart, Stop, PreTaskExec, PostTaskExec, Manual	Not evaluated. The hook always fires

Omitting matcher means the hook always matches. For file-related triggers, the {{filePath}} template variable is available inside a command action and expands to the path of the file that triggered the hook.

Exit-code behavior

For command actions, the exit code carries meaning:

Exit code	Behavior
0	Success. STDOUT is added to the agent’s context for SessionStart and UserPromptSubmit. For every other trigger STDOUT is ignored.
2	Blocks the action (PreToolUse and UserPromptSubmit only). STDERR is returned to the agent.
Other	A warning with the command’s STDERR is shown to you, and execution proceeds.

Why a successful hook can look silent

Because a 0 exit only surfaces STDOUT for SessionStart and UserPromptSubmit, a successful PostFileSave or PostToolUse hook that just prints to stdout shows you nothing. To observe those triggers, write to a log file or exit non-zero so the STDERR warning is shown. (The lesson’s warm-up uses a SessionStart hook precisely because its STDOUT is surfaced.)