@rk0429/agentic-relay 0.5.0 → 0.6.1

package/dist/relay.mjs

@@ -158,19 +158,117 @@ var init_recursion_guard = __esm({
 // src/mcp-server/tools/spawn-agent.ts
 import { z as z2 } from "zod";
 import { nanoid as nanoid2 } from "nanoid";
+import { existsSync, readFileSync } from "fs";
+import { join as join6 } from "path";
+function buildContextInjection(metadata) {
+  const parts = [];
+  if (metadata.stateContent && typeof metadata.stateContent === "string") {
+    parts.push(`<context-injection type="state">
+${metadata.stateContent}
+</context-injection>`);
+  }
+  if (Array.isArray(metadata.results) && metadata.results.length > 0) {
+    const formatted = metadata.results.map((r, i) => `[${i + 1}] ${r.title} (${r.date}, score: ${r.score})
+${r.snippet}`).join("\n\n");
+    parts.push(`<context-injection type="search-results">
+${formatted}
+</context-injection>`);
+  }
+  return parts.join("\n\n");
+}
+function readPreviousState(dailynoteDir) {
+  try {
+    const statePath = join6(dailynoteDir, "_state.md");
+    if (existsSync(statePath)) {
+      return readFileSync(statePath, "utf-8");
+    }
+    return null;
+  } catch (error) {
+    logger.warn(
+      `Failed to read _state.md: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
+function readAgentDefinition(definitionPath) {
+  try {
+    if (!existsSync(definitionPath)) {
+      logger.warn(`Agent definition file not found at ${definitionPath}`);
+      return null;
+    }
+    const content = readFileSync(definitionPath, "utf-8");
+    if (content.trim().length === 0) {
+      logger.warn(`Agent definition file is empty at ${definitionPath}`);
+      return null;
+    }
+    return content;
+  } catch (error) {
+    logger.warn(
+      `Failed to read agent definition: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
+function readSkillContext(skillContext) {
+  try {
+    const skillMdPath = join6(skillContext.skillPath, "SKILL.md");
+    if (!existsSync(skillMdPath)) {
+      logger.warn(
+        `SKILL.md not found at ${skillMdPath}`
+      );
+      return null;
+    }
+    const parts = [];
+    const skillContent = readFileSync(skillMdPath, "utf-8");
+    parts.push(skillContent);
+    if (skillContext.subskill) {
+      const subskillPath = join6(
+        skillContext.skillPath,
+        "subskills",
+        skillContext.subskill,
+        "SUBSKILL.md"
+      );
+      if (existsSync(subskillPath)) {
+        const subskillContent = readFileSync(subskillPath, "utf-8");
+        parts.push(subskillContent);
+      } else {
+        logger.warn(
+          `SUBSKILL.md not found at ${subskillPath}`
+        );
+      }
+    }
+    return parts.join("\n\n");
+  } catch (error) {
+    logger.warn(
+      `Failed to read skill context: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
 function buildContextFromEnv() {
   const traceId = process.env["RELAY_TRACE_ID"] ?? `trace-${nanoid2()}`;
   const parentSessionId = process.env["RELAY_PARENT_SESSION_ID"] ?? null;
   const depth = Number(process.env["RELAY_DEPTH"] ?? "0");
   return { traceId, parentSessionId, depth };
 }
-async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2) {
+async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector) {
+  let effectiveBackend = input.backend;
+  if (backendSelector) {
+    const availableBackends = registry2.listIds();
+    const selectionContext = {
+      availableBackends,
+      preferredBackend: input.preferredBackend,
+      agentType: input.agent,
+      taskType: input.taskType
+    };
+    effectiveBackend = backendSelector.selectBackend(selectionContext);
+  }
   const envContext = buildContextFromEnv();
   const promptHash = RecursionGuard.hashPrompt(input.prompt);
   const context = {
     traceId: envContext.traceId,
     depth: envContext.depth,
-    backend: input.backend,
+    backend: effectiveBackend,
     promptHash
   };
   const guardResult = guard.canSpawn(context);
@@ -183,27 +281,54 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       stderr: `Spawn blocked: ${guardResult.reason}`
     };
   }
-  const adapter = registry2.get(input.backend);
+  const adapter = registry2.get(effectiveBackend);
   const installed = await adapter.isInstalled();
   if (!installed) {
     return {
       sessionId: "",
       exitCode: 1,
       stdout: "",
-      stderr: `Backend "${input.backend}" is not available. Use list_available_backends to see available options.`
+      stderr: `Backend "${effectiveBackend}" is not available. Use list_available_backends to see available options.`
     };
   }
+  const spawnStartedAt = (/* @__PURE__ */ new Date()).toISOString();
   const session = await sessionManager2.create({
-    backendId: input.backend,
+    backendId: effectiveBackend,
     parentSessionId: envContext.parentSessionId ?? void 0,
     depth: envContext.depth + 1
   });
+  let collectedMetadata = {};
+  if (hooksEngine2 && !input.resumeSessionId) {
+    try {
+      const cwd = process.cwd();
+      const dailynoteDir = join6(cwd, "daily_note");
+      const hookInput = {
+        schemaVersion: "1.0",
+        event: "session-init",
+        sessionId: session.relaySessionId,
+        backendId: effectiveBackend,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        data: {
+          workingDirectory: cwd,
+          dailynoteDir,
+          isFirstSession: !existsSync(join6(dailynoteDir, "_state.md")),
+          previousState: readPreviousState(dailynoteDir)
+        }
+      };
+      const { mergedMetadata } = await hooksEngine2.emitAndCollectMetadata("session-init", hookInput);
+      collectedMetadata = { ...collectedMetadata, ...mergedMetadata };
+    } catch (error) {
+      logger.warn(
+        `session-init hook error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
   if (hooksEngine2) {
     try {
       const hookInput = {
         event: "pre-spawn",
         sessionId: session.relaySessionId,
-        backendId: input.backend,
+        backendId: effectiveBackend,
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         data: {
           prompt: input.prompt,
@@ -211,13 +336,40 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
           model: input.model
         }
       };
-      await hooksEngine2.emit("pre-spawn", hookInput);
+      const { mergedMetadata } = await hooksEngine2.emitAndCollectMetadata("pre-spawn", hookInput);
+      collectedMetadata = { ...collectedMetadata, ...mergedMetadata };
     } catch (error) {
       logger.debug(
         `pre-spawn hook error: ${error instanceof Error ? error.message : String(error)}`
       );
     }
   }
+  const injectionText = buildContextInjection(collectedMetadata);
+  let enhancedSystemPrompt = injectionText ? input.systemPrompt ? `${input.systemPrompt}
+
+${injectionText}` : injectionText : input.systemPrompt;
+  if (input.skillContext) {
+    const skillText = readSkillContext(input.skillContext);
+    if (skillText) {
+      const wrapped = `<skill-context path="${input.skillContext.skillPath}"${input.skillContext.subskill ? ` subskill="${input.skillContext.subskill}"` : ""}>
+${skillText}
+</skill-context>`;
+      enhancedSystemPrompt = enhancedSystemPrompt ? `${enhancedSystemPrompt}
+
+${wrapped}` : wrapped;
+    }
+  }
+  if (input.agentDefinition) {
+    const defText = readAgentDefinition(input.agentDefinition.definitionPath);
+    if (defText) {
+      const wrapped = `<agent-definition source="${input.agentDefinition.definitionPath}">
+${defText}
+</agent-definition>`;
+      enhancedSystemPrompt = enhancedSystemPrompt ? `${enhancedSystemPrompt}
+
+${wrapped}` : wrapped;
+    }
+  }
   try {
     let result;
     if (input.resumeSessionId) {
@@ -226,7 +378,7 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
           sessionId: session.relaySessionId,
           exitCode: 1,
           stdout: "",
-          stderr: `Backend "${input.backend}" does not support session continuation (continueSession).`
+          stderr: `Backend "${effectiveBackend}" does not support session continuation (continueSession).`
         };
       }
       result = await adapter.continueSession(input.resumeSessionId, input.prompt);
@@ -234,7 +386,7 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       result = await adapter.execute({
         prompt: input.prompt,
         agent: input.agent,
-        systemPrompt: input.systemPrompt,
+        systemPrompt: enhancedSystemPrompt,
         model: input.model,
         maxTurns: input.maxTurns,
         mcpContext: {
@@ -251,7 +403,7 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       );
       contextMonitor2.updateUsage(
         session.relaySessionId,
-        input.backend,
+        effectiveBackend,
         estimatedTokens
       );
     }
@@ -260,15 +412,27 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
     await sessionManager2.update(session.relaySessionId, { status });
     if (hooksEngine2) {
       try {
+        const postSpawnData = {
+          exitCode: result.exitCode,
+          status,
+          taskDescription: input.prompt,
+          startedAt: spawnStartedAt,
+          backgroundMode: false,
+          sessionId: session.relaySessionId,
+          selectedBackend: effectiveBackend
+        };
+        if (input.agent !== void 0) {
+          postSpawnData.agentType = input.agent;
+        }
+        if (input.model !== void 0) {
+          postSpawnData.model = input.model;
+        }
         const hookInput = {
           event: "post-spawn",
           sessionId: session.relaySessionId,
-          backendId: input.backend,
+          backendId: effectiveBackend,
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          data: {
-            exitCode: result.exitCode,
-            status
-          }
+          data: postSpawnData
         };
         await hooksEngine2.emit("post-spawn", hookInput);
       } catch (hookError) {
@@ -308,7 +472,16 @@ var init_spawn_agent = __esm({
       systemPrompt: z2.string().optional(),
       resumeSessionId: z2.string().optional(),
       model: z2.string().optional(),
-      maxTurns: z2.number().optional()
+      maxTurns: z2.number().optional(),
+      skillContext: z2.object({
+        skillPath: z2.string().describe("Path to the skill directory (e.g., '.agents/skills/software-engineer/')"),
+        subskill: z2.string().optional().describe("Specific subskill to activate")
+      }).optional().describe("Skill context to inject into the subagent's system prompt"),
+      agentDefinition: z2.object({
+        definitionPath: z2.string().describe("Path to the agent definition file (e.g., '.claude/agents/software-engineer.md')")
+      }).optional().describe("Agent definition file to inject into the sub-agent's system prompt"),
+      preferredBackend: z2.enum(["claude", "codex", "gemini"]).optional().describe("Preferred backend override. Takes priority over automatic selection based on agent/task type."),
+      taskType: z2.enum(["code", "document", "analysis", "mixed"]).optional().describe("Task type hint for automatic backend selection when preferredBackend is not specified.")
     });
   }
 });
@@ -397,6 +570,65 @@ var init_list_available_backends = __esm({
   }
 });
 
+// src/core/backend-selector.ts
+var DEFAULT_AGENT_TO_BACKEND_MAP, TASK_TYPE_TO_BACKEND_MAP, DEFAULT_BACKEND, BackendSelector;
+var init_backend_selector = __esm({
+  "src/core/backend-selector.ts"() {
+    "use strict";
+    DEFAULT_AGENT_TO_BACKEND_MAP = {
+      "software-engineer": "codex",
+      "devops-engineer": "codex",
+      "skill-developer": "codex",
+      "security-auditor": "codex",
+      "analytics-engineer": "codex",
+      "payments-billing": "codex"
+    };
+    TASK_TYPE_TO_BACKEND_MAP = {
+      code: "codex",
+      document: "claude",
+      analysis: "claude",
+      mixed: "claude"
+    };
+    DEFAULT_BACKEND = "claude";
+    BackendSelector = class {
+      defaultBackend;
+      agentToBackendMap;
+      constructor(config) {
+        this.defaultBackend = config?.defaultBackend ?? DEFAULT_BACKEND;
+        this.agentToBackendMap = config?.agentToBackendMap ?? DEFAULT_AGENT_TO_BACKEND_MAP;
+      }
+      selectBackend(context) {
+        const { availableBackends, preferredBackend, agentType, taskType } = context;
+        if (availableBackends.length === 0) {
+          throw new Error("No backends available");
+        }
+        if (preferredBackend && availableBackends.includes(preferredBackend)) {
+          return preferredBackend;
+        }
+        if (agentType) {
+          const mapped = this.agentToBackendMap[agentType];
+          if (mapped && availableBackends.includes(mapped)) {
+            return mapped;
+          }
+          if (!mapped && availableBackends.includes("claude")) {
+            return "claude";
+          }
+        }
+        if (taskType) {
+          const mapped = TASK_TYPE_TO_BACKEND_MAP[taskType];
+          if (mapped && availableBackends.includes(mapped)) {
+            return mapped;
+          }
+        }
+        if (availableBackends.includes(this.defaultBackend)) {
+          return this.defaultBackend;
+        }
+        return availableBackends[0];
+      }
+    };
+  }
+});
+
 // src/mcp-server/server.ts
 var server_exports = {};
 __export(server_exports, {
@@ -417,6 +649,7 @@ var init_server = __esm({
     init_list_sessions();
     init_get_context_status();
     init_list_available_backends();
+    init_backend_selector();
     init_logger();
     RelayMCPServer = class {
       constructor(registry2, sessionManager2, guardConfig, hooksEngine2, contextMonitor2) {
@@ -425,6 +658,7 @@ var init_server = __esm({
         this.hooksEngine = hooksEngine2;
         this.contextMonitor = contextMonitor2;
         this.guard = new RecursionGuard(guardConfig);
+        this.backendSelector = new BackendSelector();
         this.server = new McpServer({
           name: "agentic-relay",
           version: "0.4.0"
@@ -433,10 +667,11 @@ var init_server = __esm({
       }
       server;
       guard;
+      backendSelector;
       registerTools() {
         this.server.tool(
           "spawn_agent",
-          "Spawn a sub-agent on the specified backend CLI (Claude Code, Codex CLI, or Gemini CLI). The agent executes the given prompt in non-interactive mode and returns the result. Use 'agent' for named agent configurations (Claude only), or 'systemPrompt' for custom role instructions (all backends).",
+          "Spawn a sub-agent on the specified backend CLI (Claude Code, Codex CLI, or Gemini CLI). The agent executes the given prompt in non-interactive mode and returns the result. Use 'agent' for named agent configurations (Claude only), 'systemPrompt' for custom role instructions (all backends), 'skillContext' to inject a skill definition (SKILL.md/SUBSKILL.md), 'agentDefinition' to inject an agent definition file into the sub-agent's system prompt, 'preferredBackend' to override automatic backend selection, or 'taskType' to hint at the task nature for backend selection.",
           {
             backend: z5.enum(["claude", "codex", "gemini"]),
             prompt: z5.string(),
@@ -446,7 +681,16 @@ var init_server = __esm({
             ),
             resumeSessionId: z5.string().optional(),
             model: z5.string().optional(),
-            maxTurns: z5.number().optional()
+            maxTurns: z5.number().optional(),
+            skillContext: z5.object({
+              skillPath: z5.string().describe("Path to the skill directory (e.g., '.agents/skills/software-engineer/')"),
+              subskill: z5.string().optional().describe("Specific subskill to activate")
+            }).optional().describe("Skill context to inject into the sub-agent's system prompt"),
+            agentDefinition: z5.object({
+              definitionPath: z5.string().describe("Path to the agent definition file (e.g., '.claude/agents/software-engineer.md')")
+            }).optional().describe("Agent definition file to inject into the sub-agent's system prompt"),
+            preferredBackend: z5.enum(["claude", "codex", "gemini"]).optional().describe("Preferred backend override. Takes priority over automatic selection based on agent/task type."),
+            taskType: z5.enum(["code", "document", "analysis", "mixed"]).optional().describe("Task type hint for automatic backend selection when preferredBackend is not specified.")
           },
           async (params) => {
             try {
@@ -456,7 +700,8 @@ var init_server = __esm({
                 this.sessionManager,
                 this.guard,
                 this.hooksEngine,
-                this.contextMonitor
+                this.contextMonitor,
+                this.backendSelector
               );
               const isError = result.exitCode !== 0;
               const text = isError ? `Error (exit ${result.exitCode}): ${result.stderr || result.stdout}` : `Session: ${result.sessionId}
@@ -607,7 +852,7 @@ ${result.stdout}`;
 
 // src/bin/relay.ts
 import { defineCommand as defineCommand10, runMain } from "citty";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { homedir as homedir6 } from "os";
 
 // src/infrastructure/process-manager.ts
@@ -736,6 +981,10 @@ var AdapterRegistry = class {
     this.factories.clear();
     return [...this.adapters.values()];
   }
+  /** Return registered backend IDs without instantiating lazy adapters */
+  listIds() {
+    return [.../* @__PURE__ */ new Set([...this.adapters.keys(), ...this.factories.keys()])];
+  }
 };
 
 // src/adapters/base-adapter.ts
@@ -894,6 +1143,17 @@ var CLAUDE_NESTING_ENV_VARS = [
   "CLAUDE_CODE_SSE_PORT",
   "CLAUDE_CODE_ENTRYPOINT"
 ];
+var DEFAULT_CLAUDE_SDK_TIMEOUT_MS = 5 * 60 * 1e3;
+function getClaudeSdkTimeoutMs() {
+  const envVal = process.env["RELAY_CLAUDE_TIMEOUT_MS"];
+  if (envVal) {
+    const parsed = Number(envVal);
+    if (!Number.isNaN(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return DEFAULT_CLAUDE_SDK_TIMEOUT_MS;
+}
 var ClaudeAdapter = class extends BaseAdapter {
   id = "claude";
   command = "claude";
@@ -962,11 +1222,16 @@ var ClaudeAdapter = class extends BaseAdapter {
     }
     const env = this.buildCleanEnv(flags);
     const permissionMode = this.getPermissionMode();
+    const timeoutMs = getClaudeSdkTimeoutMs();
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), timeoutMs);
     try {
       const { query } = await loadClaudeSDK();
       const options = {
+        abortController,
         env,
         cwd: process.cwd(),
+        mcpServers: {},
         ...flags.model ? { model: flags.model } : {},
         ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {},
         ...flags.systemPrompt ? { systemPrompt: flags.systemPrompt } : {}
@@ -1002,11 +1267,20 @@ var ClaudeAdapter = class extends BaseAdapter {
         ...sessionId ? { nativeSessionId: sessionId } : {}
       };
     } catch (error) {
+      if (abortController.signal.aborted) {
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: `Claude SDK query timed out after ${timeoutMs}ms`
+        };
+      }
       return {
         exitCode: 1,
         stdout: "",
         stderr: error instanceof Error ? error.message : String(error)
       };
+    } finally {
+      clearTimeout(timer);
     }
   }
   async *executeStreaming(flags) {
@@ -1015,11 +1289,16 @@ var ClaudeAdapter = class extends BaseAdapter {
     }
     const env = this.buildCleanEnv(flags);
     const permissionMode = this.getPermissionMode();
+    const timeoutMs = getClaudeSdkTimeoutMs();
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), timeoutMs);
     try {
       const { query } = await loadClaudeSDK();
       const options = {
+        abortController,
         env,
         cwd: process.cwd(),
+        mcpServers: {},
         ...flags.model ? { model: flags.model } : {},
         ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {},
         ...flags.systemPrompt ? { systemPrompt: flags.systemPrompt } : {}
@@ -1079,22 +1358,29 @@ var ClaudeAdapter = class extends BaseAdapter {
         }
       }
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorMessage = abortController.signal.aborted ? `Claude SDK query timed out after ${timeoutMs}ms` : error instanceof Error ? error.message : String(error);
       yield { type: "error", message: errorMessage };
       yield {
         type: "done",
         result: { exitCode: 1, stdout: "", stderr: errorMessage }
       };
+    } finally {
+      clearTimeout(timer);
     }
   }
   async continueSession(nativeSessionId, prompt) {
+    const timeoutMs = getClaudeSdkTimeoutMs();
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), timeoutMs);
     try {
       const { query } = await loadClaudeSDK();
       const permissionMode = this.getPermissionMode();
       const options = {
+        abortController,
         resume: nativeSessionId,
         maxTurns: 1,
-        cwd: process.cwd()
+        cwd: process.cwd(),
+        mcpServers: {}
       };
       if (permissionMode === "bypassPermissions") {
         options.permissionMode = "bypassPermissions";
@@ -1118,11 +1404,20 @@ var ClaudeAdapter = class extends BaseAdapter {
         stderr: ""
       };
     } catch (error) {
+      if (abortController.signal.aborted) {
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: `Claude SDK query timed out after ${timeoutMs}ms`
+        };
+      }
       return {
         exitCode: 1,
         stdout: "",
         stderr: error instanceof Error ? error.message : String(error)
       };
+    } finally {
+      clearTimeout(timer);
     }
   }
   async resumeSession(sessionId, flags) {
@@ -2031,6 +2326,7 @@ var mcpServerConfigSchema = z.object({
   env: z.record(z.string()).optional()
 });
 var hookEventSchema = z.enum([
+  "session-init",
   "pre-prompt",
   "post-response",
   "on-error",
@@ -2046,8 +2342,19 @@ var hookDefinitionSchema = z.object({
   enabled: z.boolean().optional(),
   onError: z.enum(["ignore", "warn", "abort"]).optional()
 });
+var hookChainStepSchema = z.object({
+  stepId: z.string(),
+  hook: hookDefinitionSchema,
+  pipeOutput: z.boolean().optional()
+});
+var hookChainSchema = z.object({
+  name: z.string(),
+  steps: z.array(hookChainStepSchema).min(1),
+  onError: z.enum(["ignore", "warn", "fail"]).optional()
+});
 var hooksConfigSchema = z.object({
-  definitions: z.array(hookDefinitionSchema)
+  definitions: z.array(hookDefinitionSchema),
+  chains: z.array(hookChainSchema).optional()
 });
 var backendContextConfigSchema = z.object({
   contextWindow: z.number().positive().optional(),
@@ -2345,6 +2652,7 @@ var HooksEngine = class _HooksEngine {
   static COMMAND_PATTERN = /^[a-zA-Z0-9_./-]+$/;
   static ARG_PATTERN = /^[a-zA-Z0-9_.=:/-]+$/;
   definitions = [];
+  chains = [];
   registered = false;
   validateCommand(command) {
     if (!command || command.trim().length === 0) {
@@ -2385,6 +2693,7 @@ var HooksEngine = class _HooksEngine {
         return false;
       }
     });
+    this.chains = config.chains ?? [];
     if (!this.registered) {
       for (const event of this.getUniqueEvents()) {
         this.eventBus.on(event, async () => {
@@ -2426,10 +2735,132 @@ var HooksEngine = class _HooksEngine {
     await this.eventBus.emit(event, input);
     return results;
   }
+  /**
+   * Emit a hook event, execute all matching hooks, and return merged metadata.
+   * Merge rule: later hooks overwrite earlier hooks' metadata fields.
+   * If any hook returns allow: false, subsequent hooks are skipped.
+   */
+  async emitAndCollectMetadata(event, hookInput) {
+    const matchingDefs = this.definitions.filter((def) => def.event === event);
+    const results = [];
+    let mergedMetadata = {};
+    for (const def of matchingDefs) {
+      try {
+        const result = await this.executeHook(def, hookInput);
+        results.push(result);
+        if (result.output.metadata && typeof result.output.metadata === "object") {
+          mergedMetadata = { ...mergedMetadata, ...result.output.metadata };
+        }
+        if (!result.output.allow) {
+          logger.info(
+            `Hook "${def.command}" returned allow: false, skipping subsequent hooks for event "${event}"`
+          );
+          break;
+        }
+      } catch (error) {
+        const strategy = def.onError ?? "warn";
+        const message = error instanceof Error ? error.message : String(error);
+        if (strategy === "abort") {
+          throw new Error(
+            `Hook "${def.command}" failed (abort): ${message}`
+          );
+        }
+        if (strategy === "warn") {
+          logger.warn(
+            `Hook "${def.command}" failed (warn): ${message}`
+          );
+        }
+        results.push({
+          exitCode: 1,
+          stdout: "",
+          stderr: message,
+          durationMs: 0,
+          output: { ...DEFAULT_HOOK_OUTPUT }
+        });
+      }
+    }
+    await this.eventBus.emit(event, hookInput);
+    return { results, mergedMetadata };
+  }
   /** Get the count of enabled definitions for a given event */
   getDefinitionCount(event) {
     return this.definitions.filter((def) => def.event === event).length;
   }
+  /** Get all loaded chain names */
+  getChainNames() {
+    return this.chains.map((c) => c.name);
+  }
+  /**
+   * Execute a named hook chain.
+   * Steps execute in sequence. If pipeOutput is true, previous step's
+   * HookOutput is merged into the next step's HookInput.data.
+   */
+  async executeChain(chainName, initialInput) {
+    const chain = this.chains.find((c) => c.name === chainName);
+    if (!chain) {
+      throw new Error(`Hook chain "${chainName}" not found`);
+    }
+    const errorStrategy = chain.onError ?? "warn";
+    const stepResults = [];
+    let mergedMetadata = {};
+    let previousOutput;
+    let overallSuccess = true;
+    for (const step of chain.steps) {
+      const startTime = Date.now();
+      let stepInput;
+      if (step.pipeOutput && previousOutput) {
+        stepInput = {
+          ...initialInput,
+          data: {
+            ...initialInput.data,
+            ...previousOutput.metadata,
+            _previousMessage: previousOutput.message,
+            _previousAllow: previousOutput.allow
+          }
+        };
+      } else {
+        stepInput = { ...initialInput };
+      }
+      try {
+        const result = await this.executeHook(step.hook, stepInput);
+        const durationMs = Date.now() - startTime;
+        stepResults.push({
+          stepId: step.stepId,
+          success: true,
+          output: result.output,
+          durationMs
+        });
+        if (result.output.metadata && typeof result.output.metadata === "object") {
+          mergedMetadata = { ...mergedMetadata, ...result.output.metadata };
+        }
+        previousOutput = result.output;
+      } catch (error) {
+        const durationMs = Date.now() - startTime;
+        const message = error instanceof Error ? error.message : String(error);
+        stepResults.push({
+          stepId: step.stepId,
+          success: false,
+          error: message,
+          durationMs
+        });
+        overallSuccess = false;
+        if (errorStrategy === "fail") {
+          break;
+        }
+        if (errorStrategy === "warn") {
+          logger.warn(
+            `Hook chain "${chainName}" step "${step.stepId}" failed (warn): ${message}`
+          );
+        }
+      }
+    }
+    return {
+      chainName,
+      stepResults,
+      success: overallSuccess,
+      mergedMetadata
+    };
+  }
   async executeHook(def, input) {
     this.validateCommand(def.command);
     this.validateArgs(def.args ?? []);
@@ -3387,7 +3818,7 @@ function createVersionCommand(registry2) {
 // src/commands/doctor.ts
 import { defineCommand as defineCommand8 } from "citty";
 import { access, constants, readdir as readdir2 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { homedir as homedir5 } from "os";
 import { execFile } from "child_process";
 import { promisify } from "util";
@@ -3448,8 +3879,8 @@ async function checkConfig(configManager2) {
   }
 }
 async function checkSessionsDir() {
-  const relayHome2 = process.env["RELAY_HOME"] ?? join6(homedir5(), ".relay");
-  const sessionsDir = join6(relayHome2, "sessions");
+  const relayHome2 = process.env["RELAY_HOME"] ?? join7(homedir5(), ".relay");
+  const sessionsDir = join7(relayHome2, "sessions");
   try {
     await access(sessionsDir, constants.W_OK);
     return {
@@ -3562,8 +3993,8 @@ async function checkBackendAuthEnv() {
   return results;
 }
 async function checkSessionsDiskUsage() {
-  const relayHome2 = process.env["RELAY_HOME"] ?? join6(homedir5(), ".relay");
-  const sessionsDir = join6(relayHome2, "sessions");
+  const relayHome2 = process.env["RELAY_HOME"] ?? join7(homedir5(), ".relay");
+  const sessionsDir = join7(relayHome2, "sessions");
   try {
     const entries = await readdir2(sessionsDir);
     const fileCount = entries.length;
@@ -3637,7 +4068,7 @@ function createDoctorCommand(registry2, configManager2) {
 init_logger();
 import { defineCommand as defineCommand9 } from "citty";
 import { mkdir as mkdir6, writeFile as writeFile6, access as access2, readFile as readFile6 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 var DEFAULT_CONFIG2 = {
   defaultBackend: "claude",
   backends: {},
@@ -3651,8 +4082,8 @@ function createInitCommand() {
     },
     async run() {
       const projectDir = process.cwd();
-      const relayDir = join7(projectDir, ".relay");
-      const configPath = join7(relayDir, "config.json");
+      const relayDir = join8(projectDir, ".relay");
+      const configPath = join8(relayDir, "config.json");
       try {
         await access2(relayDir);
         logger.info(
@@ -3668,7 +4099,7 @@ function createInitCommand() {
         "utf-8"
       );
       logger.success(`Created ${configPath}`);
-      const gitignorePath = join7(projectDir, ".gitignore");
+      const gitignorePath = join8(projectDir, ".gitignore");
       try {
         const gitignoreContent = await readFile6(gitignorePath, "utf-8");
         if (!gitignoreContent.includes(".relay/config.local.json")) {
@@ -3693,8 +4124,8 @@ registry.registerLazy("claude", () => new ClaudeAdapter(processManager));
 registry.registerLazy("codex", () => new CodexAdapter(processManager));
 registry.registerLazy("gemini", () => new GeminiAdapter(processManager));
 var sessionManager = new SessionManager();
-var relayHome = process.env["RELAY_HOME"] ?? join8(homedir6(), ".relay");
-var projectRelayDir = join8(process.cwd(), ".relay");
+var relayHome = process.env["RELAY_HOME"] ?? join9(homedir6(), ".relay");
+var projectRelayDir = join9(process.cwd(), ".relay");
 var configManager = new ConfigManager(relayHome, projectRelayDir);
 var authManager = new AuthManager(registry);
 var eventBus = new EventBus();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rk0429/agentic-relay",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Unified CLI proxy for Claude Code, Codex CLI, and Gemini CLI with MCP-based multi-layer sub-agent orchestration",
   "type": "module",
   "license": "Apache-2.0",