46 lines
2.1 KiB
Markdown
46 lines
2.1 KiB
Markdown
---
|
|
type: reference
|
|
title: "Claude Code hook lifecycle — which events can inject model-visible context"
|
|
summary: "Which Claude Code hook events can emit additionalContext the model acts on (SessionStart, UserPromptSubmit, PreCompact) versus events that can only run deterministic scripts (SessionEnd) or fire per-turn (Stop), and why session-close rituals must be user-invoked skills rather than hook injections."
|
|
tags:
|
|
- type/reference
|
|
- tool/claude-code
|
|
- domain/context-engineering
|
|
scope: global
|
|
date: 2026-07-10
|
|
last_updated: 2026-07-10
|
|
related:
|
|
- "[[claude-code-system-prompt-customization-surface]]"
|
|
- "[[memsearch-sessionstart-injection-hardcoded]]"
|
|
---
|
|
|
|
# Claude Code hook lifecycle — which events can inject model-visible context
|
|
|
|
Not all hook events can put instructions in front of the model. Grouped by capability:
|
|
|
|
## Can inject `additionalContext` the model acts on
|
|
|
|
- **SessionStart** — fires on `startup|resume|clear|compact` (matcher-selectable). Including
|
|
`compact` in the matcher makes injected rules survive context compaction, not just the
|
|
first turn.
|
|
- **UserPromptSubmit** — per-prompt injection; the mid-session injection point.
|
|
- **PreCompact** — can shape what survives compaction.
|
|
|
|
## Cannot instruct the model
|
|
|
|
- **SessionEnd** — fires *after* the model's last turn. There are no more turns, so emitted
|
|
content is never seen by the model. Only useful for deterministic scripts: sync, cleanup,
|
|
journaling.
|
|
- **Stop** — fires when Claude finishes *every* turn and can block/redirect, but it is
|
|
per-turn (noisy) — wrong for once-per-session rituals.
|
|
|
|
## Consequence
|
|
|
|
A "session-close ritual" (commit + update docs + write handoff) **cannot be a hook
|
|
injection** — there is no injection point at session end. It must be a user-invoked
|
|
skill/command (e.g. a `/wrap` skill) whose file holds the ritual instructions.
|
|
|
|
Corollary design pattern: a SessionStart composer hook (script reads prompt files from a
|
|
directory, concatenates, emits as `additionalContext`) is the right home for always-true
|
|
session rules; session-*end* model behavior always routes through a command the user types.
|