Pipeline Hooks

Pipeline Hooks

The pipeline hooks system provides a 10-stage middleware architecture for the agent loop. Hooks intercept agent processing at key stages, running in priority order within each stage.

Hook Stages

INPUT → pre-assess → ASSESS (metacognition) → post-assess
  → pre-reason → REASON (LLM call) → post-reason
  → pre-tool → TOOL EXECUTE → post-tool
  → pre-reflect → REFLECT → post-reflect
  → pre-output → OUTPUT → post-output

Built-in Hooks

Hook	Stage	Priority	Purpose
@cortex/injection-guard	pre-reason	5	Prompt injection detection
@cortex/model-quartermaster	pre-llm, post-llm	5	MQM intelligent model selection
@cortex/quartermaster	pre-tool, post-tool	6	Tool orchestration learning
@cortex/summarization	pre-reason	8	Context compaction at 80K token threshold
@cortex/content-safety	pre-output	10	Content filtering before output
@cortex/loop-detection	pre-tool	12	Per-file edit tracking (warns after 5+ edits)
@cortex/tool-output-sandbox	post-tool	15	Large output capture to session storage
@cortex/pre-completion-checklist	post-reason	20	Build-Verify-Fix enforcement
@cortex/audit-log	post-output	150	Session/turn logging (non-disableable)
@cortex/cost-tracker	post-tool, post-output	200	Token/cost metrics

Execution Model

• Sync hooks — block the pipeline; 5-second timeout per hook
• Async hooks — fire-and-forget; 15-second timeout per hook
• Priority-ordered — lower priority numbers execute first within each stage
• Abort support — any hook can return { abort } to stop the pipeline immediately

Hook Actions

Action	Description
abort	Stop the pipeline with a message
modifyInput	Mutate the input before processing
modifyLLMResponse	Modify the LLM's response
modifyOutput	Modify the final output
injectMessages	Add messages to the conversation (spliced into context)
sideEffects	Log, emit metrics, store data, send notifications

modifyInput applies at any pipeline stage (not just pre-assess). store side effects persist to session-scoped storage with accessor and cleanup functions.

Plugin Hooks

Plugins can contribute their own hooks to the pipeline via the plugin lifecycle. Per-session state is cleaned up on turn end to prevent unbounded memory growth in summarizationStates and loopStates Maps.

Hooks CLI

cortex hooks list                          # List all registered hooks
cortex hooks disable @cortex/cost-tracker  # Disable a hook
cortex hooks init                          # Initialize hook configuration

REST API

Method	Path	Description
GET	/api/hooks	List pipeline hooks
POST	/api/hooks/:name/disable	Disable a specific hook

See Also

• Architecture — System design including hooks
• Request Flow — Hooks in the request lifecycle
• Agent Loop — How hooks integrate into agent turns