@oisincoveney/pipeline 1.13.0 → 1.15.0

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/defaults/install-manifest.json

@@ -5,71 +5,5 @@
       "source": "oisincoveney/skills",
       "args": ["--agent", "codex", "--skill", "*", "--yes", "--copy"]
     }
-  ],
-  "mcps": [
-    {
-      "name": "oisin-pipeline-backlog",
-      "transport": "stdio",
-      "command": "backlog",
-      "args": ["mcp", "start"]
-    },
-    {
-      "name": "oisin-pipeline-context7",
-      "transport": "remote",
-      "catalog": "context7"
-    },
-    {
-      "name": "oisin-pipeline-github-readonly",
-      "transport": "stdio",
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "-e",
-        "GITHUB_PERSONAL_ACCESS_TOKEN",
-        "ghcr.io/github/github-mcp-server",
-        "stdio",
-        "--read-only"
-      ],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
-      }
-    },
-    {
-      "name": "oisin-pipeline-playwright",
-      "transport": "stdio",
-      "catalog": "playwright"
-    },
-    {
-      "name": "oisin-pipeline-qdrant",
-      "transport": "remote",
-      "url": "https://memory-mcp.momokaya.ee/mcp/",
-      "optionalRegistration": true,
-      "headers": {
-        "Authorization": {
-          "sources": [{ "env": "MEMORY_MCP_BASIC_AUTH", "prefix": "Basic " }]
-        }
-      }
-    },
-    {
-      "name": "oisin-pipeline-semgrep",
-      "transport": "stdio",
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/semgrep/mcp", "-t", "stdio"]
-    },
-    {
-      "name": "oisin-pipeline-serena",
-      "transport": "stdio",
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/oraios/serena",
-        "serena",
-        "start-mcp-server",
-        "--project-from-cwd",
-        "--context=codex"
-      ]
-    }
   ]
 }

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,85 @@ 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";
+  }, z.core.$strict>>;
+  mcp_gateway: z.ZodOptional<z.ZodObject<{
+    default_profile: z.ZodOptional<z.ZodString>;
+    mode: z.ZodEnum<{
+      hosted: "hosted";
+      local: "local";
     }>;
-    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>>>;
+    provider: z.ZodLiteral<"toolhive">;
+    token_env: z.ZodDefault<z.ZodString>;
+    url_env: z.ZodDefault<z.ZodString>;
+  }, z.core.$strict>>;
   mcp_servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     bearer_token_env_var: z.ZodOptional<z.ZodString>;
@@ -203,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<{
@@ -231,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>;
@@ -274,10 +320,10 @@ 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>;
@@ -324,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

@@ -1,5 +1,4 @@
 import { resolveFileReference } from "./path-refs.js";
-import { parseJson } from "./safe-json.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseDocument } from "yaml";
@@ -23,6 +22,7 @@ const HOOK_EVENTS = [
 	"node.start",
 	"node.success",
 	"node.error",
+	"node.finish",
 	"gate.failure"
 ];
 const TOOL_NAMES = [
@@ -55,6 +55,7 @@ const RETRY_REASONS = [
 	"timeout"
 ];
 const SCHEDULE_BASELINES = ["epic", "pipe"];
+const PIPELINE_GATEWAY_SERVER_ID = "pipeline-gateway";
 var PipelineConfigError = class extends Error {
 	code;
 	issues;
@@ -126,21 +127,13 @@ const mcpServerSchema = z.object({
 		path: ["bearer_token_env_var"]
 	});
 });
-const mcpServerRefSchema = z.object({
-	format: z.literal("mcp-json").default("mcp-json"),
-	id: z.string().min(1).optional(),
-	path: z.string().min(1)
+const mcpGatewaySchema = z.object({
+	default_profile: z.string().min(1).optional(),
+	mode: z.enum(["hosted", "local"]),
+	provider: z.literal("toolhive"),
+	token_env: z.string().min(1).default("PIPELINE_MCP_GATEWAY_TOKEN"),
+	url_env: z.string().min(1).default("PIPELINE_MCP_GATEWAY_URL")
 }).strict();
-const mcpServerDefinitionSchema = z.union([mcpServerSchema, z.object({ ref: mcpServerRefSchema }).strict()]);
-const mcpJsonServerSchema = z.object({
-	args: z.array(z.string()).optional(),
-	bearer_token_env_var: z.string().min(1).optional(),
-	command: z.string().min(1).optional(),
-	env: z.record(z.string(), z.string()).optional(),
-	headers: z.record(z.string(), z.string()).optional(),
-	url: z.string().min(1).optional()
-}).passthrough();
-const mcpJsonFileSchema = z.object({ mcpServers: strictRecord(mcpJsonServerSchema) }).passthrough();
 const instructionsSchema = z.object({
 	inline: z.string().min(1).optional(),
 	path: z.string().min(1).optional()
@@ -237,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({
@@ -282,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(),
@@ -319,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({
@@ -327,7 +363,8 @@ const runnersFileSchema = z.object({
 	version: z.literal(1)
 }).strict();
 const profilesFileSchema = z.object({
-	mcp_servers: strictRecord(mcpServerDefinitionSchema).default({}),
+	mcp_gateway: mcpGatewaySchema.optional(),
+	mcp_servers: strictRecord(z.never()).default({}),
 	profiles: strictRecord(profileSchema).default({}),
 	rules: strictRecord(pathRefSchema).default({}),
 	skills: strictRecord(pathRefSchema).default({}),
@@ -336,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(),
@@ -346,7 +386,11 @@ 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,
 	profiles: strictRecord(profileSchema).default({}),
@@ -464,12 +508,12 @@ function parsePipelineConfigParts(sources, projectRoot, sourcePaths = {
 	const runners = parseYamlAs(sources.runners, sourcePaths.runners, runnersFileSchema);
 	const profiles = parseYamlAs(sources.profiles, sourcePaths.profiles, profilesFileSchema);
 	const pipeline = parseYamlAs(sources.pipeline, sourcePaths.pipeline, pipelineFileSchema);
-	const mcpServers = resolveMcpServerDefinitions(profiles.mcp_servers, projectRoot);
 	return validatePipelineConfig({
 		default_workflow: pipeline.default_workflow,
 		entrypoints: pipeline.entrypoints,
 		hooks: pipeline.hooks,
-		mcp_servers: mcpServers,
+		...profiles.mcp_gateway ? { mcp_gateway: profiles.mcp_gateway } : {},
+		mcp_servers: profiles.mcp_servers,
 		orchestrator: pipeline.orchestrator,
 		profiles: profiles.profiles,
 		rules: profiles.rules,
@@ -497,61 +541,6 @@ function parseYamlAs(source, sourcePath, schema) {
 	})));
 	return parsed.data;
 }
-function resolveMcpServerDefinitions(registry, projectRoot) {
-	return Object.fromEntries(Object.entries(registry).map(([id, definition]) => [id, "ref" in definition ? resolveMcpServerRef(id, definition.ref, projectRoot) : definition]));
-}
-function resolveMcpServerRef(id, ref, projectRoot) {
-	if (!projectRoot) throw validationError([{
-		path: `mcp_servers.${id}.ref.path`,
-		message: "MCP server refs require a project root"
-	}]);
-	const filePath = resolveFileReference(projectRoot, ref.path);
-	if (!existsSync(filePath)) throw validationError([{
-		path: `mcp_servers.${id}.ref.path`,
-		message: `referenced MCP config file '${ref.path}' does not exist`
-	}]);
-	const parsed = parseMcpJsonFile(id, ref, filePath);
-	const importedId = ref.id ?? id;
-	const imported = parsed.mcpServers[importedId];
-	if (!imported) throw validationError([{
-		path: `mcp_servers.${id}.ref.id`,
-		message: `MCP config '${ref.path}' does not declare server '${importedId}'`
-	}]);
-	const normalized = normalizeMcpJsonServer(imported);
-	const result = mcpServerSchema.safeParse(normalized);
-	if (!result.success) throw validationError(result.error.issues.map((issue) => ({
-		path: [`mcp_servers.${id}.ref`, ...issue.path].join("."),
-		message: issue.message
-	})));
-	return result.data;
-}
-function parseMcpJsonFile(id, ref, filePath) {
-	let raw;
-	try {
-		raw = parseJson(readFileSync(filePath, "utf8"), `MCP config ${ref.path}`);
-	} catch (err) {
-		throw new PipelineConfigError("PIPELINE_CONFIG_PARSE_ERROR", `Failed to parse MCP config ${ref.path}`, [{
-			path: `mcp_servers.${id}.ref.path`,
-			message: err instanceof Error ? err.message : String(err)
-		}]);
-	}
-	const parsed = mcpJsonFileSchema.safeParse(raw);
-	if (!parsed.success) throw validationError(parsed.error.issues.map((issue) => ({
-		path: [`mcp_servers.${id}.ref`, ...issue.path].join("."),
-		message: issue.message
-	})));
-	return parsed.data;
-}
-function normalizeMcpJsonServer(server) {
-	return {
-		...server.command ? { command: server.command } : {},
-		...server.args ? { args: server.args } : {},
-		...server.env ? { env: server.env } : {},
-		...server.url ? { url: server.url } : {},
-		...server.headers ? { headers: server.headers } : {},
-		...server.bearer_token_env_var ? { bearer_token_env_var: server.bearer_token_env_var } : {}
-	};
-}
 function validatePipelineConfig(rawConfig, projectRoot, options = {}) {
 	const parsed = configSchema.safeParse(rawConfig);
 	if (!parsed.success) throw validationError(parsed.error.issues.map((issue) => ({
@@ -565,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}'`
 	});
@@ -584,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);
@@ -606,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);
@@ -629,7 +631,10 @@ function validateActor(label, path, actor, runner, config, issues, projectRoot,
 	validatePath(`${path}.instructions.path`, actor.instructions.path, projectRoot, issues, options);
 	validateReferences(`${path}.rules`, actor.rules, config.rules, "rule", issues);
 	validateReferences(`${path}.skills`, actor.skills, config.skills, "skill", issues);
-	validateReferences(`${path}.mcp_servers`, actor.mcp_servers, config.mcp_servers, "MCP server", issues);
+	validateReferences(`${path}.mcp_servers`, actor.mcp_servers, config.mcp_gateway ? {
+		...config.mcp_servers,
+		[PIPELINE_GATEWAY_SERVER_ID]: {}
+	} : config.mcp_servers, "MCP server", issues);
 	validateBooleanCapability(`${path}.rules`, actor.rules, runner.capabilities.rules, "rules", issues);
 	validateBooleanCapability(`${path}.skills`, actor.skills, runner.capabilities.skills, "skills", issues);
 	validateBooleanCapability(`${path}.mcp_servers`, actor.mcp_servers, runner.capabilities.mcp_servers, "MCP servers", issues);
@@ -638,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({
@@ -661,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);
 }