@oisincoveney/pipeline 1.14.0 → 1.15.1

package/README.md

@@ -188,7 +188,10 @@ default_workflow: default
 
 orchestrator:
   profile: orchestrator
-  hooks: []
+
+hooks:
+  functions: {}
+  on: {}
 
 workflows:
   default:
@@ -353,7 +356,7 @@ runners:
 - JSON Schema gates validate structure only. Use `verdict` and `acceptance`
   gates to enforce semantic pass/fail and per-criterion coverage.
 - Command hooks support host policy controls, sanitized environments, timeouts,
-  output limits, and JSON payloads on stdin.
+  output limits, and JSON file input/result payloads.
 
 ## App-Facing API
 
@@ -377,6 +380,16 @@ import {
 } from "@oisincoveney/pipeline/runtime";
 ```
 
+Hook modules can import the typed helper and result contract:
+
+```ts
+import {
+  defineHook,
+  type HookContext,
+  type HookResult,
+} from "@oisincoveney/pipeline/hooks";
+```
+
 Runner Job producers can import the shared payload contract:
 
 ```ts

package/dist/config.d.ts

@@ -6,7 +6,7 @@ declare const RUNNERS_CONFIG_PATH = ".pipeline/runners.yaml";
 declare const PROFILES_CONFIG_PATH = ".pipeline/profiles.yaml";
 declare const RUNNER_TYPES: readonly ["codex", "opencode", "command"];
 declare const NODE_KINDS: readonly ["agent", "command", "builtin", "group", "parallel", "workflow"];
-declare const HOOK_EVENTS: readonly ["workflow.start", "workflow.success", "workflow.failure", "workflow.complete", "node.start", "node.success", "node.error", "gate.failure"];
+declare const HOOK_EVENTS: readonly ["workflow.start", "workflow.success", "workflow.failure", "workflow.complete", "node.start", "node.success", "node.error", "node.finish", "gate.failure"];
 declare const GATE_KINDS: readonly ["acceptance", "artifact", "builtin", "changed_files", "command", "json_schema", "verdict"];
 declare const SCHEDULE_BASELINES: readonly ["epic", "pipe"];
 type PipelineConfigErrorCode = "PIPELINE_CONFIG_LEGACY_UNSUPPORTED" | "PIPELINE_CONFIG_MISSING" | "PIPELINE_CONFIG_PARSE_ERROR" | "PIPELINE_CONFIG_VALIDATION_ERROR";
@@ -88,7 +88,6 @@ declare const workflowNodeBaseSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"verdict">;
   }, z.core.$strict>], "kind">>>;
-  hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
   id: z.ZodString;
   needs: z.ZodOptional<z.ZodArray<z.ZodString>>;
   retries: z.ZodOptional<z.ZodObject<{
@@ -146,7 +145,6 @@ declare const workflowSchema: z.ZodObject<{
     max_parallel_nodes: z.ZodOptional<z.ZodNumber>;
     timeout_ms: z.ZodOptional<z.ZodNumber>;
   }, z.core.$strict>>;
-  hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
   nodes: z.ZodArray<z.ZodType<WorkflowNode, unknown, z.core.$ZodTypeInternals<WorkflowNode, unknown>>>;
 }, z.core.$strict>;
 declare const configSchema: z.ZodObject<{
@@ -164,36 +162,75 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$loose>>;
     schedule: z.ZodString;
   }, z.core.$strict>]>>>;
-  hooks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-    builtin: z.ZodOptional<z.ZodString>;
-    command: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    enabled: z.ZodOptional<z.ZodBoolean>;
-    env: z.ZodOptional<z.ZodObject<{
-      passthrough: z.ZodOptional<z.ZodArray<z.ZodString>>;
-      set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  hooks: z.ZodDefault<z.ZodObject<{
+    functions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+      kind: z.ZodLiteral<"module">;
+      module: z.ZodString;
+      permissions: z.ZodOptional<z.ZodObject<{
+        filesystem: z.ZodOptional<z.ZodEnum<{
+          "read-only": "read-only";
+          "workspace-write": "workspace-write";
+        }>>;
+        network: z.ZodOptional<z.ZodEnum<{
+          inherit: "inherit";
+          disabled: "disabled";
+        }>>;
+      }, z.core.$strict>>;
+      returns: z.ZodOptional<z.ZodObject<{
+        schema: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+      timeout_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+      command: z.ZodArray<z.ZodString>;
+      env: z.ZodOptional<z.ZodObject<{
+        passthrough: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+      }, z.core.$strict>>;
+      kind: z.ZodLiteral<"command">;
+      output_limit_bytes: z.ZodOptional<z.ZodNumber>;
+      protocol: z.ZodDefault<z.ZodObject<{
+        input: z.ZodLiteral<"file">;
+        result: z.ZodLiteral<"file">;
+      }, z.core.$strict>>;
+      returns: z.ZodOptional<z.ZodObject<{
+        schema: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+      timeout_ms: z.ZodOptional<z.ZodNumber>;
+      trusted: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "kind">>>;
+    on: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+      failure: z.ZodDefault<z.ZodEnum<{
+        fail: "fail";
+        ignore: "ignore";
+      }>>;
+      function: z.ZodString;
+      id: z.ZodString;
+      result: z.ZodOptional<z.ZodObject<{
+        pass_to: z.ZodOptional<z.ZodEnum<{
+          downstream: "downstream";
+        }>>;
+        publish: z.ZodOptional<z.ZodBoolean>;
+        save_as: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+      where: z.ZodOptional<z.ZodObject<{
+        gate: z.ZodOptional<z.ZodString>;
+        node: z.ZodOptional<z.ZodString>;
+        workflow: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+      with: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>>;
+    policy: z.ZodOptional<z.ZodObject<{
+      commands: z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        "trusted-only": "trusted-only";
+      }>>;
+      modules: z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+      }>>;
     }, z.core.$strict>>;
-    event: z.ZodEnum<{
-      "workflow.start": "workflow.start";
-      "workflow.success": "workflow.success";
-      "workflow.failure": "workflow.failure";
-      "workflow.complete": "workflow.complete";
-      "node.start": "node.start";
-      "node.success": "node.success";
-      "node.error": "node.error";
-      "gate.failure": "gate.failure";
-    }>;
-    kind: z.ZodEnum<{
-      builtin: "builtin";
-      command: "command";
-    }>;
-    output_limit_bytes: z.ZodOptional<z.ZodNumber>;
-    payload: z.ZodOptional<z.ZodEnum<{
-      stdin: "stdin";
-    }>>;
-    required: z.ZodOptional<z.ZodBoolean>;
-    timeout_ms: z.ZodOptional<z.ZodNumber>;
-    trusted: z.ZodOptional<z.ZodBoolean>;
-  }, z.core.$strict>>>;
+  }, z.core.$strict>>;
   mcp_gateway: z.ZodOptional<z.ZodObject<{
     default_profile: z.ZodOptional<z.ZodString>;
     mode: z.ZodEnum<{
@@ -213,7 +250,6 @@ declare const configSchema: z.ZodObject<{
     url: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>>;
   orchestrator: z.ZodObject<{
-    hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
     profile: z.ZodString;
   }, z.core.$strict>;
   profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -241,10 +277,10 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>;
     output: z.ZodOptional<z.ZodObject<{
       format: z.ZodEnum<{
+        json_schema: "json_schema";
         text: "text";
         json: "json";
         jsonl: "jsonl";
-        json_schema: "json_schema";
       }>;
       repair: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -257,7 +293,6 @@ declare const configSchema: z.ZodObject<{
     runner: z.ZodString;
     skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-      task: "task";
       read: "read";
       list: "list";
       grep: "grep";
@@ -265,6 +300,7 @@ declare const configSchema: z.ZodObject<{
       bash: "bash";
       edit: "edit";
       write: "write";
+      task: "task";
     }>>>;
   }, z.core.$strict>>>;
   rules: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -284,15 +320,14 @@ declare const configSchema: z.ZodObject<{
         disabled: "disabled";
       }>>>;
       output_formats: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        json_schema: "json_schema";
         text: "text";
         json: "json";
         jsonl: "jsonl";
-        json_schema: "json_schema";
       }>>>;
       rules: z.ZodOptional<z.ZodBoolean>;
       skills: z.ZodOptional<z.ZodBoolean>;
       tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        task: "task";
         read: "read";
         list: "list";
         grep: "grep";
@@ -300,6 +335,7 @@ declare const configSchema: z.ZodObject<{
         bash: "bash";
         edit: "edit";
         write: "write";
+        task: "task";
       }>>>;
     }, z.core.$strict>;
     command: z.ZodOptional<z.ZodString>;
@@ -334,7 +370,6 @@ declare const configSchema: z.ZodObject<{
       max_parallel_nodes: z.ZodOptional<z.ZodNumber>;
       timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
-    hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
     nodes: z.ZodArray<z.ZodType<WorkflowNode, unknown, z.core.$ZodTypeInternals<WorkflowNode, unknown>>>;
   }, z.core.$strict>>>;
 }, z.core.$strict>;

package/dist/config.js

@@ -22,6 +22,7 @@ const HOOK_EVENTS = [
 	"node.start",
 	"node.success",
 	"node.error",
+	"node.finish",
 	"gate.failure"
 ];
 const TOOL_NAMES = [
@@ -229,27 +230,72 @@ const profileSchema = z.object({
 	skills: z.array(z.string()).optional(),
 	tools: z.array(z.enum(TOOL_NAMES)).optional()
 }).strict();
-const orchestratorSchema = z.object({
-	hooks: z.array(z.string()).optional(),
-	profile: z.string()
-}).strict();
+const orchestratorSchema = z.object({ profile: z.string() }).strict();
 const hookEnvSchema = z.object({
 	passthrough: z.array(z.string()).optional(),
 	set: z.record(z.string(), z.string()).optional()
 }).strict();
-const hookSchema = z.object({
-	builtin: z.string().optional(),
-	command: z.array(z.string()).optional(),
-	enabled: z.boolean().optional(),
+const hookPermissionsSchema = z.object({
+	filesystem: z.enum(FILESYSTEM_MODES).optional(),
+	network: z.enum(NETWORK_MODES).optional()
+}).strict();
+const hookReturnsSchema = z.object({ schema: z.string().min(1).optional() }).strict();
+const moduleHookFunctionSchema = z.object({
+	kind: z.literal("module"),
+	module: z.string().min(1),
+	permissions: hookPermissionsSchema.optional(),
+	returns: hookReturnsSchema.optional(),
+	timeout_ms: z.number().int().positive().optional()
+}).strict();
+const commandHookProtocolSchema = z.object({
+	input: z.literal("file"),
+	result: z.literal("file")
+}).strict();
+const commandHookFunctionSchema = z.object({
+	command: z.array(z.string()).min(1),
 	env: hookEnvSchema.optional(),
-	event: z.enum(HOOK_EVENTS),
-	kind: z.enum(["command", "builtin"]),
+	kind: z.literal("command"),
 	output_limit_bytes: z.number().int().positive().optional(),
-	payload: z.enum(["stdin"]).optional(),
-	required: z.boolean().optional(),
+	protocol: commandHookProtocolSchema.default({
+		input: "file",
+		result: "file"
+	}),
+	returns: hookReturnsSchema.optional(),
 	timeout_ms: z.number().int().positive().optional(),
 	trusted: z.boolean().optional()
 }).strict();
+const hookFunctionSchema = z.discriminatedUnion("kind", [moduleHookFunctionSchema, commandHookFunctionSchema]);
+const hookBindingWhereSchema = z.object({
+	gate: z.string().optional(),
+	node: z.string().optional(),
+	workflow: z.string().optional()
+}).strict();
+const hookBindingResultSchema = z.object({
+	pass_to: z.enum(["downstream"]).optional(),
+	publish: z.boolean().optional(),
+	save_as: z.string().min(1).optional()
+}).strict();
+const hookBindingSchema = z.object({
+	failure: z.enum(["fail", "ignore"]).default("ignore"),
+	function: z.string().min(1),
+	id: z.string().min(1),
+	result: hookBindingResultSchema.optional(),
+	where: hookBindingWhereSchema.optional(),
+	with: z.record(z.string(), z.unknown()).optional()
+}).strict();
+const hookPolicySchema = z.object({
+	commands: z.enum([
+		"allow",
+		"trusted-only",
+		"deny"
+	]).optional(),
+	modules: z.enum(["allow", "deny"]).optional()
+}).strict();
+const hooksConfigSchema = z.object({
+	functions: strictRecord(hookFunctionSchema).default({}),
+	on: strictRecord(z.array(hookBindingSchema)).default({}),
+	policy: hookPolicySchema.optional()
+}).strict();
 const taskContextResolverSchema = z.object({ type: z.string().min(1) }).passthrough();
 const nodeTaskContextSchema = z.object({
 	acceptance_criteria: z.array(z.object({
@@ -274,7 +320,6 @@ const schedulePolicySchema = z.object({
 const workflowNodeBaseSchema = z.object({
 	artifacts: z.array(artifactSchema).optional(),
 	gates: z.array(gateSchema).optional(),
-	hooks: z.array(z.string()).optional(),
 	id: z.string(),
 	needs: z.array(z.string()).optional(),
 	retries: retriesSchema.optional(),
@@ -311,7 +356,6 @@ const workflowNodeSchema = z.lazy(() => z.discriminatedUnion("kind", [
 const workflowSchema = z.object({
 	description: z.string().optional(),
 	execution: workflowExecutionSchema.optional(),
-	hooks: z.array(z.string()).optional(),
 	nodes: z.array(workflowNodeSchema)
 }).strict();
 const runnersFileSchema = z.object({
@@ -329,7 +373,10 @@ const profilesFileSchema = z.object({
 const pipelineFileSchema = z.object({
 	default_workflow: z.string(),
 	entrypoints: strictRecord(entrypointSchema).default({}),
-	hooks: strictRecord(hookSchema).default({}),
+	hooks: hooksConfigSchema.default({
+		functions: {},
+		on: {}
+	}),
 	orchestrator: orchestratorSchema,
 	schedules: strictRecord(schedulePolicySchema).default({}),
 	task_context: taskContextResolverSchema.optional(),
@@ -339,7 +386,10 @@ const pipelineFileSchema = z.object({
 const configSchema = z.object({
 	default_workflow: z.string(),
 	entrypoints: strictRecord(entrypointSchema).default({}),
-	hooks: strictRecord(hookSchema).default({}),
+	hooks: hooksConfigSchema.default({
+		functions: {},
+		on: {}
+	}),
 	mcp_gateway: mcpGatewaySchema.optional(),
 	mcp_servers: strictRecord(mcpServerSchema).default({}),
 	orchestrator: orchestratorSchema,
@@ -504,11 +554,10 @@ function validatePipelineConfig(rawConfig, projectRoot, options = {}) {
 	validateRegistryIds("rules", config.rules, issues);
 	validateRegistryIds("skills", config.skills, issues);
 	validateRegistryIds("mcp_servers", config.mcp_servers, issues);
-	validateRegistryIds("hooks", config.hooks, issues);
+	validateRegistryIds("hooks.functions", config.hooks.functions, issues);
 	validateRegistryIds("workflows", config.workflows, issues);
 	validateRegistryIds("entrypoints", config.entrypoints, issues);
-	if (config.profiles[config.orchestrator.profile]) validateReferences("orchestrator.hooks", config.orchestrator.hooks, config.hooks, "hook", issues);
-	else issues.push({
+	if (!config.profiles[config.orchestrator.profile]) issues.push({
 		path: "orchestrator.profile",
 		message: `orchestrator references missing profile '${config.orchestrator.profile}'`
 	});
@@ -523,16 +572,7 @@ function validatePipelineConfig(rawConfig, projectRoot, options = {}) {
 		}
 		validateProfile(profileId, profile, runner, config, issues, projectRoot, options);
 	}
-	for (const [hookId, hook] of Object.entries(config.hooks)) {
-		if (hook.kind === "command" && !hook.command) issues.push({
-			path: `hooks.${hookId}.command`,
-			message: `command hook '${hookId}' must declare command`
-		});
-		if (hook.kind === "builtin" && !hook.builtin) issues.push({
-			path: `hooks.${hookId}.builtin`,
-			message: `builtin hook '${hookId}' must declare builtin`
-		});
-	}
+	validateHookConfig(config, issues, projectRoot, options);
 	for (const [ruleId, rule] of Object.entries(config.rules)) validatePath(`rules.${ruleId}.path`, rule.path, projectRoot, issues, options);
 	for (const [skillId, skill] of Object.entries(config.skills)) validatePath(`skills.${skillId}.path`, skill.path, projectRoot, issues, options);
 	for (const [workflowId, workflow] of Object.entries(config.workflows)) validateWorkflow(workflowId, workflow, config, issues, projectRoot, options);
@@ -545,6 +585,29 @@ function validateRegistryIds(name, registry, issues) {
 		message: `registry id '${id}' must match ${ID_RE.source}`
 	});
 }
+function validateHookConfig(config, issues, projectRoot, options = {}) {
+	const allowedEvents = new Set(HOOK_EVENTS);
+	for (const [functionId, hookFunction] of Object.entries(config.hooks.functions)) validatePath(`hooks.functions.${functionId}.returns.schema`, hookFunction.returns?.schema, projectRoot, issues, options);
+	for (const [event, bindings] of Object.entries(config.hooks.on)) {
+		if (!allowedEvents.has(event)) {
+			issues.push({
+				path: `hooks.on.${event}`,
+				message: `unsupported hook event '${event}'`
+			});
+			continue;
+		}
+		for (const [index, binding] of bindings.entries()) {
+			if (!ID_RE.test(binding.id)) issues.push({
+				path: `hooks.on.${event}.${index}.id`,
+				message: `hook binding id '${binding.id}' must match ${ID_RE.source}`
+			});
+			if (!config.hooks.functions[binding.function]) issues.push({
+				path: `hooks.on.${event}.${index}.function`,
+				message: `hook binding '${binding.id}' references missing function '${binding.function}'`
+			});
+		}
+	}
+}
 function validateProfile(profileId, profile, runner, config, issues, projectRoot, options = {}) {
 	validateActor(`profile '${profileId}'`, `profiles.${profileId}`, profile, runner, config, issues, projectRoot, options);
 	validateListCapability(`profiles.${profileId}.output.format`, profile.output?.format ? [profile.output.format] : void 0, runner.capabilities.output_formats, "output format", issues);
@@ -580,7 +643,6 @@ function validateActor(label, path, actor, runner, config, issues, projectRoot,
 	validateListCapability(`${path}.network.mode`, actor.network?.mode ? [actor.network.mode] : void 0, runner.capabilities.network, "network mode", issues);
 }
 function validateWorkflow(workflowId, workflow, config, issues, projectRoot, options = {}) {
-	validateReferences(`workflows.${workflowId}.hooks`, workflow.hooks, config.hooks, "hook", issues);
 	const nodeIds = /* @__PURE__ */ new Set();
 	for (const node of workflow.nodes) {
 		if (nodeIds.has(node.id)) issues.push({
@@ -603,7 +665,6 @@ function validateWorkflowNode(workflowId, node, nodeIds, config, issues) {
 		path: `workflows.${workflowId}.nodes.${node.id}.needs`,
 		message: `node '${node.id}' references missing dependency '${need}'`
 	});
-	validateReferences(`workflows.${workflowId}.nodes.${node.id}.hooks`, node.hooks, config.hooks, "hook", issues);
 	validateWorkflowNodeKind(workflowId, node, config, issues);
 	if (node.kind === "parallel") validateParallelWorkflowNode(workflowId, node, config, issues);
 }

package/dist/hooks.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+//#region src/hooks.d.ts
+declare const hookResultSchema: z.ZodObject<{
+  artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    contentType: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    path: z.ZodString;
+  }, z.core.$strict>>>;
+  outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  patch: z.ZodOptional<z.ZodObject<{
+    runLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    taskContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strict>>;
+  status: z.ZodEnum<{
+    fail: "fail";
+    pass: "pass";
+    skip: "skip";
+  }>;
+  summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type HookResult = z.infer<typeof hookResultSchema>;
+interface HookContext {
+  event: {
+    gateId?: string;
+    hookId: string;
+    nodeId?: string;
+    type: string;
+    workflowId: string;
+  };
+  failure?: {
+    evidence: string[];
+    gate: string;
+    nodeId?: string;
+    reason: string;
+  };
+  input: Record<string, unknown>;
+  node?: {
+    id: string;
+  };
+  results: Record<string, HookResult>;
+  task: string;
+  taskContext?: {
+    acceptanceCriteria?: Array<{
+      id: string;
+      text: string;
+    }>;
+    description?: string;
+    id?: string;
+    title?: string;
+  };
+  workflow: {
+    id: string;
+  };
+}
+type HookFunction = (context: HookContext) => HookResult | Promise<HookResult>;
+declare function defineHook<T extends HookFunction>(hook: T): T;
+declare function parseHookResult(value: unknown): HookResult;
+//#endregion
+export { HookContext, HookFunction, HookResult, defineHook, hookResultSchema, parseHookResult };

package/dist/hooks.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+//#region src/hooks.ts
+const hookResultSchema = z.object({
+	artifacts: z.array(z.object({
+		contentType: z.string().optional(),
+		name: z.string().min(1),
+		path: z.string().min(1)
+	}).strict()).optional(),
+	outputs: z.record(z.string(), z.unknown()).optional(),
+	patch: z.object({
+		runLabels: z.record(z.string(), z.string()).optional(),
+		taskContext: z.record(z.string(), z.unknown()).optional()
+	}).strict().optional(),
+	status: z.enum([
+		"pass",
+		"fail",
+		"skip"
+	]),
+	summary: z.string().optional()
+}).strict();
+function defineHook(hook) {
+	return hook;
+}
+function parseHookResult(value) {
+	return hookResultSchema.parse(value);
+}
+//#endregion
+export { defineHook, hookResultSchema, parseHookResult };

package/dist/index.js

@@ -110,6 +110,7 @@ function formatAgentProgress(event) {
 		case "agent.finish": return `Agent finished: ${event.nodeId} runner=${event.runnerId ?? "unknown"} exit=${event.exitCode}`;
 		case "hook.start": return `Hook starting: ${event.hookId} event=${event.event}${event.nodeId ? ` node=${event.nodeId}` : ""}`;
 		case "hook.finish": return `Hook ${event.passed ? "passed" : "failed"}: ${event.hookId}${event.reason ? ` (${event.reason})` : ""}`;
+		case "hook.result": return `Hook result: ${event.hookId} ${event.status}${event.summary ? ` (${event.summary})` : ""}`;
 		default: return null;
 	}
 }
@@ -497,7 +498,6 @@ function formatSelectedWorkflowPlan(config, worktreePath, flags) {
 	return formatWorkflowPlan(config, worktreePath, resolveWorkflowSelection(config, flags.workflow, flags.entrypoint));
 }
 function formatCompiledWorkflowPlan(config, worktreePath, plan) {
-	const workflow = config.workflows[plan.workflowId];
 	const lines = [`Workflow: ${plan.workflowId}`];
 	lines.push(formatOrchestratorPlan(config, worktreePath));
 	lines.push(`Batches: ${plan.parallelBatches.map((batch) => `[${batch.map((node) => node.id).join(", ")}]`).join(" -> ")}`);
@@ -505,7 +505,8 @@ function formatCompiledWorkflowPlan(config, worktreePath, plan) {
 		if (node.kind === "parallel" && node.children?.length) lines.push(`${node.id}(parallel: ${node.children.map((child) => child.id).join(", ")})`);
 		lines.push(formatWorkflowPlanNode(node, config, worktreePath));
 	}
-	if (workflow?.hooks?.length) lines.push(`Workflow hooks: ${workflow.hooks.join(", ")}`);
+	const workflowHooks = Object.entries(config.hooks.on).flatMap(([event, bindings]) => bindings.filter((binding) => binding.where?.workflow === plan.workflowId).map((binding) => `${event}:${binding.id}`));
+	if (workflowHooks.length > 0) lines.push(`Workflow hooks: ${workflowHooks.join(", ")}`);
 	return lines.join("\n");
 }
 function formatWorkflowPlanNode(node, config, worktreePath) {
@@ -522,8 +523,7 @@ function formatWorkflowPlanNode(node, config, worktreePath) {
 		launch ? `runner=${launch.runnerId}` : "",
 		launch ? `strategy=${launch.strategy}` : "",
 		node.gates?.length ? `gates=${node.gates.length}` : "gates=0",
-		node.artifacts?.length ? `artifacts=${node.artifacts.map((artifact) => artifact.path).join(",")}` : "artifacts=none",
-		node.hooks?.length ? `hooks=${node.hooks.join(",")}` : ""
+		node.artifacts?.length ? `artifacts=${node.artifacts.map((artifact) => artifact.path).join(",")}` : "artifacts=none"
 	].filter(Boolean).join(" ");
 }
 function resolveWorkflowSelection(config, workflowId, entrypointId) {
@@ -548,7 +548,7 @@ function formatOrchestratorPlan(config, worktreePath) {
 		formatList("rules", orchestrator.rules),
 		formatList("skills", orchestrator.skills),
 		formatList("mcp_servers", orchestrator.mcp_servers),
-		formatList("hooks", config.orchestrator.hooks)
+		formatList("hooks", Object.keys(config.hooks.functions))
 	].filter(Boolean).join(" ");
 }
 function formatList(label, items) {

package/dist/install-commands.js

@@ -58,10 +58,7 @@ function nativeProfileEntries(host, config) {
 function orchestratorProfile(config) {
 	const profile = config.profiles[config.orchestrator.profile];
 	if (!profile) throw new Error(`Orchestrator profile '${config.orchestrator.profile}' is not declared.`);
-	return {
-		...profile,
-		hooks: config.orchestrator.hooks
-	};
+	return { ...profile };
 }
 function resolvedHostModel(config, host, profile) {
 	const runner = config.runners[profile.runner];
@@ -132,7 +129,6 @@ function grants(actor) {
 		`mcp_servers: ${(actor.mcp_servers ?? []).join(", ") || "none"}`,
 		`filesystem: ${actor.filesystem?.mode ?? "default"}`,
 		`network: ${actor.network?.mode ?? "default"}`,
-		..."hooks" in actor ? [`hooks: ${(actor.hooks ?? []).join(", ") || "none"}`] : [],
 		..."output" in actor ? [`output: ${actor.output?.format ?? "text"}`] : []
 	].join("\n");
 }
@@ -149,6 +145,7 @@ function orchestratorBlock(config) {
 	return [
 		"Configured orchestrator:",
 		grants(orchestratorProfile(config)),
+		`hooks: ${Object.keys(config.hooks.functions).join(", ") || "none"}`,
 		"",
 		instructionsPointer(orchestratorProfile(config))
 	].join("\n");

package/dist/pipeline-init.js

@@ -34,31 +34,35 @@ entrypoints:
 
 orchestrator:
   profile: orchestrator
-  hooks: [generated-defaults-audit]
 
 hooks:
-  generated-defaults-audit:
-    event: workflow.start
-    kind: command
-    command:
-      - node
-      - -e
-      - |
-        const fs = require("node:fs");
-        const files = [".pipeline/profiles.yaml"].filter((file) => fs.existsSync(file));
-        const text = files.map((file) => fs.readFileSync(file, "utf8")).join("\\n").toLowerCase();
-        const banned = ["atlassian", "jira", "linear", "confluence", "compass", "sentry", "deepwiki"];
-        const hits = banned.filter((item) => text.includes(item));
-        const githubUrls = [...text.matchAll(/https:\\/\\/api\\.githubcopilot\\.com\\/mcp[^"'\\s]*/g)].map((match) => match[0]);
-        const writeGithub = githubUrls.filter((url) => !url.includes("/readonly"));
-        if (hits.length || writeGithub.length) {
-          console.error(["Banned generated defaults detected.", hits.length ? "services=" + hits.join(",") : "", writeGithub.length ? "github=" + writeGithub.join(",") : ""].filter(Boolean).join(" "));
-          process.exit(1);
-        }
-    required: true
-    trusted: true
-    timeout_ms: 5000
-    output_limit_bytes: 4096
+  functions:
+    generated-defaults-audit:
+      kind: command
+      command:
+        - node
+        - -e
+        - |
+          const fs = require("node:fs");
+          const files = [".pipeline/profiles.yaml"].filter((file) => fs.existsSync(file));
+          const text = files.map((file) => fs.readFileSync(file, "utf8")).join("\\n").toLowerCase();
+          const banned = ["atlassian", "jira", "linear", "confluence", "compass", "sentry", "deepwiki"];
+          const hits = banned.filter((item) => text.includes(item));
+          const githubUrls = [...text.matchAll(/https:\\/\\/api\\.githubcopilot\\.com\\/mcp[^"'\\s]*/g)].map((match) => match[0]);
+          const writeGithub = githubUrls.filter((url) => !url.includes("/readonly"));
+          if (hits.length || writeGithub.length) {
+            console.error(["Banned generated defaults detected.", hits.length ? "services=" + hits.join(",") : "", writeGithub.length ? "github=" + writeGithub.join(",") : ""].filter(Boolean).join(" "));
+            process.exit(1);
+          }
+          fs.writeFileSync(process.env.PIPELINE_HOOK_RESULT, JSON.stringify({ status: "pass", summary: "Generated defaults audit passed" }));
+      trusted: true
+      timeout_ms: 5000
+      output_limit_bytes: 4096
+  on:
+    workflow.start:
+      - id: generated-defaults-audit
+        function: generated-defaults-audit
+        failure: fail
 
 schedules:
   pipe-schedule:
@@ -564,7 +568,7 @@ const EPIC_TRACK_ITEM_SCHEMA = z.object({
 	title: z.string().optional()
 });
 function zodJsonSchema(schema) {
-	return JSON.stringify(z.toJSONSchema(schema, { target: "draft-07" }), null, 2);
+	return JSON.stringify(z.toJSONSchema(schema, { target: "draft-2020-12" }), null, 2);
 }
 const RESEARCH_SCHEMA = zodJsonSchema(z.object({
 	ac: STRING_ARRAY_SCHEMA,