Pipeline System

The pipeline system provides a hook-based processing framework that wraps every stage of the agent turn lifecycle. Core and plugin hooks execute at 10 distinct pipeline stages with configurable priority, timeout protection, and rich modification capabilities.

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Pipeline System                         │
│                                                           │
│  10 Pipeline Stages (in order):                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
│  │pre-assess│→│post-assess│→│pre-reason│→ ...             │
│  └──────────┘  └──────────┘  └──────────┘               │
│       │              │              │                      │
│       ▼              ▼              ▼                      │
│  ┌────────────────────────────────────────────┐          │
│  │          Registered Hooks (prioritized)     │          │
│  │  Core Hooks + Plugin Hooks                  │          │
│  └────────────────────────────────────────────┘          │
└──────────────────────────────────────────────────────────┘

10 Pipeline Stages

Stage	When	Purpose
pre-assess	Before assessment	Pre-filter, context preparation
post-assess	After assessment	Validate assessment output
pre-reason	Before reasoning	Modify reasoning context / LLM request
post-reason	After reasoning	Validate reasoning / process LLM response
pre-tool	Before tool execution	Tool call filtering
post-tool	After tool execution	Tool result processing
pre-reflect	Before reflection	Modify reflection context
post-reflect	After reflection	Process reflection output
pre-output	Before final output	Modify user-facing response
post-output	After final output	Post-response side effects

Hook Interface

interface PipelineHook {
  name: string;
  stages: PipelineStage[];
  priority: number;
  async: boolean;
  disableable: boolean;
  run(ctx: PipelineContext): Promise<HookResult>;
}

interface HookResult {
  abort?: boolean;
  modifyInput?: string;
  modifyLLMResponse?: string;
  modifyOutput?: string;
  injectMessages?: Message[];
  sideEffects?: SideEffect[];
}

Built-in Core Hooks

Hook	Stage	Priority	Description
@cortex/injection-guard	pre-reason	5	Prompt injection detection
@cortex/model-quartermaster	pre-reason, post-reason	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

Hook Registration

Hooks can be registered by:

• Core system on startup
• Plugins via the plugin manager
• Custom scripts via the hooks API

Each hook has a priority (0–100) determining execution order within a stage. Hooks have timeout protection (5s sync, 15s async) to prevent pipeline stalls.

Pipeline Context

Hooks receive a read-only PipelineContext with:

• sessionId, turnId — Current session/turn identifiers
• tokensUsed, costUsd — Current consumption metrics
• toolCallsMade — Count of tool calls this turn
• setState(key, value) — Mutate pipeline state

See also: Agent Loop, Plugin System