@cleocode/core 2026.3.42 → 2026.3.44

package/src/hooks/index.ts

@@ -2,11 +2,30 @@
  * Hooks System - Barrel Export
  *
  * Central export point for the CLEO hooks system.
- * Import from here to access the hook registry, types, and handlers.
+ * Import from here to access the hook registry, types, handlers, and
+ * Zod payload validation schemas.
  *
  * @module @cleocode/cleo/hooks
  */
 
 export * from './handlers/index.js';
+export type { PayloadValidationResult } from './payload-schemas.js';
+export {
+  HookPayloadSchema,
+  OnAgentCompletePayloadSchema,
+  OnAgentSpawnPayloadSchema,
+  OnCascadeStartPayloadSchema,
+  OnErrorPayloadSchema,
+  OnFileChangePayloadSchema,
+  OnPatrolPayloadSchema,
+  OnPromptSubmitPayloadSchema,
+  OnResponseCompletePayloadSchema,
+  OnSessionEndPayloadSchema,
+  OnSessionStartPayloadSchema,
+  OnToolCompletePayloadSchema,
+  OnToolStartPayloadSchema,
+  OnWorkAvailablePayloadSchema,
+  validatePayload,
+} from './payload-schemas.js';
 export { HookRegistry, hooks } from './registry.js';
 export type * from './types.js';

package/src/hooks/payload-schemas.ts

@@ -0,0 +1,199 @@
+/**
+ * Zod validation schemas for hook event payloads.
+ *
+ * Provides runtime validation for all hook payload types defined in
+ * ./types.ts. Each schema mirrors its corresponding TypeScript interface
+ * and can be used to validate payloads at dispatch time.
+ *
+ * @module @cleocode/cleo/hooks/payload-schemas
+ */
+
+import { z } from 'zod/v4';
+import type { HookEvent } from './types.js';
+
+// ============================================================================
+// Base Payload Schema
+// ============================================================================
+
+/** Zod schema for {@link HookPayload}. */
+export const HookPayloadSchema = z.object({
+  timestamp: z.iso.datetime(),
+  sessionId: z.string().optional(),
+  taskId: z.string().optional(),
+  providerId: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+// ============================================================================
+// CAAMP-mapped Event Payload Schemas
+// ============================================================================
+
+/** Zod schema for {@link OnSessionStartPayload}. */
+export const OnSessionStartPayloadSchema = HookPayloadSchema.extend({
+  sessionId: z.string(),
+  name: z.string(),
+  scope: z.string(),
+  agent: z.string().optional(),
+});
+
+/** Zod schema for {@link OnSessionEndPayload}. */
+export const OnSessionEndPayloadSchema = HookPayloadSchema.extend({
+  sessionId: z.string(),
+  duration: z.number(),
+  tasksCompleted: z.array(z.string()),
+});
+
+/** Zod schema for {@link OnToolStartPayload}. */
+export const OnToolStartPayloadSchema = HookPayloadSchema.extend({
+  taskId: z.string(),
+  taskTitle: z.string(),
+  previousTask: z.string().optional(),
+});
+
+/** Zod schema for {@link OnToolCompletePayload}. */
+export const OnToolCompletePayloadSchema = HookPayloadSchema.extend({
+  taskId: z.string(),
+  taskTitle: z.string(),
+  status: z.enum(['done', 'archived', 'cancelled']),
+});
+
+/** Zod schema for {@link OnFileChangePayload}. */
+export const OnFileChangePayloadSchema = HookPayloadSchema.extend({
+  filePath: z.string(),
+  changeType: z.enum(['write', 'create', 'delete']),
+  sizeBytes: z.number().optional(),
+});
+
+/** Zod schema for {@link OnErrorPayload}. */
+export const OnErrorPayloadSchema = HookPayloadSchema.extend({
+  errorCode: z.union([z.number(), z.string()]),
+  message: z.string(),
+  domain: z.string().optional(),
+  operation: z.string().optional(),
+  gateway: z.string().optional(),
+  stack: z.string().optional(),
+});
+
+/** Zod schema for {@link OnPromptSubmitPayload}. */
+export const OnPromptSubmitPayloadSchema = HookPayloadSchema.extend({
+  gateway: z.string(),
+  domain: z.string(),
+  operation: z.string(),
+  source: z.string().optional(),
+});
+
+/** Zod schema for {@link OnResponseCompletePayload}. */
+export const OnResponseCompletePayloadSchema = HookPayloadSchema.extend({
+  gateway: z.string(),
+  domain: z.string(),
+  operation: z.string(),
+  success: z.boolean(),
+  durationMs: z.number().optional(),
+  errorCode: z.string().optional(),
+});
+
+// ============================================================================
+// CLEO Internal Event Payload Schemas
+// ============================================================================
+
+/** Zod schema for {@link OnWorkAvailablePayload}. */
+export const OnWorkAvailablePayloadSchema = HookPayloadSchema.extend({
+  taskIds: z.array(z.string()),
+  epicId: z.string().optional(),
+  chainId: z.string().optional(),
+  reason: z.enum(['dependency-cleared', 'new-task', 'retry', 'manual', 'patrol']).optional(),
+});
+
+/** Zod schema for {@link OnAgentSpawnPayload}. */
+export const OnAgentSpawnPayloadSchema = HookPayloadSchema.extend({
+  agentId: z.string(),
+  role: z.string(),
+  adapterId: z.string().optional(),
+  taskId: z.string().optional(),
+});
+
+/** Zod schema for {@link OnAgentCompletePayload}. */
+export const OnAgentCompletePayloadSchema = HookPayloadSchema.extend({
+  agentId: z.string(),
+  role: z.string(),
+  status: z.enum(['complete', 'partial', 'blocked', 'failed']),
+  taskId: z.string().optional(),
+  summary: z.string().optional(),
+});
+
+/** Zod schema for {@link OnCascadeStartPayload}. */
+export const OnCascadeStartPayloadSchema = HookPayloadSchema.extend({
+  cascadeId: z.string(),
+  chainId: z.string().optional(),
+  tesseraId: z.string().optional(),
+  taskIds: z.array(z.string()).optional(),
+});
+
+/** Zod schema for {@link OnPatrolPayload}. */
+export const OnPatrolPayloadSchema = HookPayloadSchema.extend({
+  watcherId: z.string(),
+  patrolType: z.enum(['health', 'sweep', 'refinery', 'watcher', 'custom']),
+  scope: z.string().optional(),
+});
+
+// ============================================================================
+// Event -> Schema Mapping
+// ============================================================================
+
+/**
+ * Map from hook event name to its corresponding Zod schema.
+ *
+ * Used by {@link validatePayload} for runtime dispatch. Events not in
+ * this map fall back to the base {@link HookPayloadSchema}.
+ */
+const EVENT_SCHEMA_MAP: Partial<Record<HookEvent, z.ZodType>> = {
+  onSessionStart: OnSessionStartPayloadSchema,
+  onSessionEnd: OnSessionEndPayloadSchema,
+  onToolStart: OnToolStartPayloadSchema,
+  onToolComplete: OnToolCompletePayloadSchema,
+  onFileChange: OnFileChangePayloadSchema,
+  onError: OnErrorPayloadSchema,
+  onPromptSubmit: OnPromptSubmitPayloadSchema,
+  onResponseComplete: OnResponseCompletePayloadSchema,
+  onWorkAvailable: OnWorkAvailablePayloadSchema,
+  onAgentSpawn: OnAgentSpawnPayloadSchema,
+  onAgentComplete: OnAgentCompletePayloadSchema,
+  onCascadeStart: OnCascadeStartPayloadSchema,
+  onPatrol: OnPatrolPayloadSchema,
+};
+
+// ============================================================================
+// Validator Function
+// ============================================================================
+
+/** Result of payload validation. */
+export interface PayloadValidationResult {
+  /** Whether the payload passed validation. */
+  valid: boolean;
+  /** Validation errors (empty when valid). */
+  errors: string[];
+}
+
+/**
+ * Validate a hook payload against its event-specific Zod schema.
+ *
+ * Falls back to the base {@link HookPayloadSchema} for events without
+ * a dedicated schema. Returns a result object rather than throwing,
+ * so callers can decide how to handle validation failures.
+ *
+ * @param event - The hook event name
+ * @param payload - The payload to validate
+ * @returns Validation result with any error messages
+ */
+export function validatePayload(event: HookEvent, payload: unknown): PayloadValidationResult {
+  const schema = EVENT_SCHEMA_MAP[event] ?? HookPayloadSchema;
+  const result = schema.safeParse(payload);
+
+  if (result.success) {
+    return { valid: true, errors: [] };
+  }
+
+  const errors = result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+
+  return { valid: false, errors };
+}

package/src/index.ts

@@ -31,12 +31,14 @@ export * from '@cleocode/contracts';
 export * as adapters from './adapters/index.js';
 export * as admin from './admin/index.js';
 export * as adrs from './adrs/index.js';
+export * as agents from './agents/index.js';
 export * as caamp from './caamp/index.js';
 export * as codebaseMap from './codebase-map/index.js';
 export * as compliance from './compliance/index.js';
 export * as context from './context/index.js';
 export * as coreHooks from './hooks/index.js';
 export * as inject from './inject/index.js';
+export * as intelligence from './intelligence/index.js';
 export * as issue from './issue/index.js';
 export * as lifecycle from './lifecycle/index.js';
 export * as coreMcp from './mcp/index.js';
@@ -71,6 +73,73 @@ export * as templates from './templates/index.js';
 export * as ui from './ui/index.js';
 export * as validation from './validation/index.js';
 
+// ---------------------------------------------------------------------------
+// Canonical Zod enum schemas (flat re-exports for Pattern 3 imports)
+// ---------------------------------------------------------------------------
+
+export {
+  // Governance enums
+  adrStatusSchema,
+  // Agent enums
+  agentInstanceStatusSchema,
+  agentTypeSchema,
+  brainConfidenceLevelSchema,
+  brainDecisionTypeSchema,
+  brainEdgeTypeSchema,
+  brainImpactLevelSchema,
+  brainLinkTypeSchema,
+  brainMemoryTypeSchema,
+  brainNodeTypeSchema,
+  brainObservationSourceTypeSchema,
+  // Brain enums
+  brainObservationTypeSchema,
+  brainOutcomeTypeSchema,
+  brainPatternTypeSchema,
+  brainStickyColorSchema,
+  brainStickyPrioritySchema,
+  brainStickyStatusSchema,
+  externalLinkTypeSchema,
+  gateStatusSchema,
+  insertAgentErrorLogSchema,
+  // Agent insert/select schemas
+  insertAgentInstanceSchema,
+  insertExternalTaskLinkSchema,
+  insertPipelineManifestSchema,
+  insertReleaseManifestSchema,
+  insertSessionSchema,
+  // Insert/select schemas
+  insertTaskSchema,
+  lifecycleEvidenceTypeSchema,
+  lifecycleGateResultSchema,
+  // Lifecycle enums
+  lifecyclePipelineStatusSchema,
+  lifecycleStageNameSchema,
+  lifecycleStageStatusSchema,
+  lifecycleTransitionTypeSchema,
+  manifestStatusSchema,
+  selectAgentErrorLogSchema,
+  selectAgentInstanceSchema,
+  selectExternalTaskLinkSchema,
+  selectPipelineManifestSchema,
+  selectReleaseManifestSchema,
+  selectSessionSchema,
+  selectTaskSchema,
+  // Session enums
+  sessionStatusSchema,
+  syncDirectionSchema,
+  taskPrioritySchema,
+  // Relation / link enums
+  taskRelationTypeSchema,
+  taskSizeSchema,
+  // Task enums
+  taskStatusSchema,
+  taskTypeSchema,
+  tokenUsageConfidenceSchema,
+  // Token usage enums
+  tokenUsageMethodSchema,
+  tokenUsageTransportSchema,
+} from './store/validation-schemas.js';
+
 // ---------------------------------------------------------------------------
 // Store layer (bundled inside core)
 // ---------------------------------------------------------------------------

package/src/inject/index.ts

@@ -13,7 +13,7 @@
  * @epic T4454
  */
 
-import type { Task, TaskFile } from '@cleocode/contracts';
+import type { Task, TaskWorkState } from '@cleocode/contracts';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 
@@ -23,23 +23,25 @@ import { getAccessor } from '../store/data-accessor.js';
  * @task T4539
  */
 function selectTasksForInjection(
-  data: TaskFile,
+  allTasks: Task[],
   opts: {
     maxTasks?: number;
     focusedOnly?: boolean;
     phase?: string;
+    focusedTaskId?: string | null;
+    currentPhase?: string | null;
   },
 ): Task[] {
   const maxTasks = opts.maxTasks ?? 8;
-  let tasks = data.tasks.filter((t) => t.status !== 'done');
+  let tasks = allTasks.filter((t) => t.status !== 'done');
 
   // Filter by focused task
-  if (opts.focusedOnly && data.focus?.currentTask) {
-    tasks = tasks.filter((t) => t.id === data.focus!.currentTask);
+  if (opts.focusedOnly && opts.focusedTaskId) {
+    tasks = tasks.filter((t) => t.id === opts.focusedTaskId);
   }
 
   // Filter by phase
-  const phase = opts.phase ?? data.project?.currentPhase ?? undefined;
+  const phase = opts.phase ?? opts.currentPhase ?? undefined;
   if (phase) {
     const phaseTasks = tasks.filter((t) => t.phase === phase);
     if (phaseTasks.length > 0) tasks = phaseTasks;
@@ -88,15 +90,13 @@ export async function injectTasks(
   const acc = accessor ?? (await getAccessor(opts.cwd));
   const { tasks: allTasks } = await acc.queryTasks({});
   const projectMeta = await acc.getMetaValue<{ currentPhase?: string }>('project');
-  const focusMeta = await acc.getMetaValue<{ currentTask?: string }>('focus');
+  const focusMeta = await acc.getMetaValue<TaskWorkState>('focus_state');
 
-  const data: TaskFile = {
-    tasks: allTasks,
-    project: projectMeta as TaskFile['project'],
-    focus: focusMeta as TaskFile['focus'],
-  } as TaskFile;
-
-  const selectedTasks = selectTasksForInjection(data, opts);
+  const selectedTasks = selectTasksForInjection(allTasks, {
+    ...opts,
+    focusedTaskId: focusMeta?.currentTask ?? null,
+    currentPhase: projectMeta?.currentPhase ?? null,
+  });
   const formatted = formatForInjection(selectedTasks);
 
   const phase = opts.phase ?? projectMeta?.currentPhase ?? null;