Hooks

Hooks run automatically — you don’t invoke them. They fire at specific points in the Claude Code lifecycle.

SessionStart

Trigger: when a Claude Code session begins

What it does:

1. Reads API key from userConfig (CLAUDE_PLUGIN_OPTION_apiKey) or falls back to ~/.prism/config.json
2. Validates key format (must start with gck_)
3. Resolves service URLs (ingest, gateway) from the config endpoint cache — falls back to fetching from the endpoint if cache is missing or expired
4. Checks OTEL settings in ~/.claude/settings.json — syncs them if they’ve drifted
5. Sets environment variables via CLAUDE_ENV_FILE:
   • Always: PRISM_THRESHOLD, PRISM_GCK_KEY, PRISM_INGEST_URL
   • If gateway enabled: ANTHROPIC_BASE_URL, ANTHROPIC_CUSTOM_HEADERS
6. Resets session state (turn count, tokens, cost, response times)
7. Shows version update notification if the plugin was recently updated

Output:

[Prism] Session started — gateway=enabled key=gck_abc12... ingest=https://ingest.prism.optra-ai.com

Note

OTEL env vars must exist before Claude Code starts — they’re read at process init. The session-start hook checks they’re correct and fixes them for the next session if they’ve drifted. The initial setup is done by /prism:setup.

UserPromptSubmit

Trigger: before each user prompt is submitted to Claude

What it does:

1. Skips processing for short/navigational prompts (<10 chars, slash commands, yes/no)
2. Scores PQ quietly using local heuristics (saved to session state for the status line)
3. Updates advisor context file (~/.prism/advisor-context.json) with session metrics
4. Shows context management nudges:
   • /clear nudge if turn count >80 or context grew >10x
   • /compact nudge if turn count >20 and context grew >3x
   • Periodic nudge every 15 turns
5. Records prompt timestamp for response-time measurement
6. Captures prompt text to the ingest service

PQ scoring criteria (used for status line display):

Factor	Points	Triggered by
File paths	+2.5	Paths like src/components/Header.tsx
Function names	+2.0	Names like handleSubmit() or parseConfig
Line numbers	+1.5	References like line 42 or :42
Error messages	+1.5	Quoted error text or stack traces
Expected behavior	+1.5	”should return”, “expected output”
Code snippets	+1.0	Inline code blocks
Multiple verbs	-1.5 each	”fix X and refactor Y and add Z”
Bundling phrases	-2.0	”and also”, “while you’re at it”
List items	-2.5	Numbered or bulleted task lists

PQ = (Specificity + Decomposition) / 2 — both scored 0–10.

Note

The submit hook never blocks your prompt — it always exits with code 0. Prompt quality coaching (rewrites, suggestions) is handled by the prism-advisor skill, which runs as an always-active skill with full project context.

Stop

Trigger: after Claude responds to your prompt

What it does:

1. Updates session counters: turn count, input/output tokens, model usage
2. Computes turn cost using model-specific pricing with cache-aware rates
3. Measures prompt-to-response elapsed time
4. Displays a compact status line (if showStatusLine is enabled):

   [Prism] 3.2s · 12K in / 2K out · $0.23 ($1.45 total) · PQ 7.5 · turn 12

5. Shows periodic context growth alerts (every 5 turns):
   • Red: turn count >80 or context grew >10x — recommends /clear
   • Yellow: context grew >3x — recommends /compact
   • Dim: every 15 turns — gentle /compact reminder
6. Model overkill detection (every 10 turns): warns if 3+ Opus turns produced <200 tokens
7. Slow response alert (every 5 turns): warns if average >20s over last 3 turns
8. Captures response summary to ingest service (first 2000 chars)
9. Queries OTEL telemetry for cache token data (stored for next turn’s cost calculation)

Status line format:

[Prism] {time} · {tokens} · {cost} · PQ {score} · turn {n}

Component	Color	Meaning
Time	Green <5s, Yellow 5–15s, Red 15+s	Response latency
Cost	Dim	~ prefix when no cache data (conservative estimate)
PQ	Green >=6, Yellow 4–6, Red <4	Prompt quality from submit handler

Model pricing (per million tokens):

Model	Input	Output	Cache Read	Cache Write
Opus 4.6	$15.00	$75.00	$1.50	$18.75
Sonnet 4.6	$3.00	$15.00	$0.30	$3.75
Haiku 4.5	$0.25	$1.25	$0.025	$0.3125

PostCompact

Trigger: after you run /compact

What it does:

1. Resets turn count to 0
2. Resets context tracking (first/last turn input tokens)
3. Clears response times array
4. Resets model overkill counter and model counts
5. Resets total cost to 0
6. Clears last PQ score and cache data

This gives the status line and context management nudges a fresh baseline after compaction.