@rk0429/agentic-relay 0.6.4 → 0.8.0

package/README.md

@@ -156,6 +156,10 @@ Example configuration:
 | `OPENAI_API_KEY` | Passed through to Codex CLI (optional with subscription) | -- |
 | `GEMINI_API_KEY` | Passed through to Gemini CLI (optional with subscription) | -- |
 
+### Security Considerations
+
+- **Claude adapter permission bypass**: By default, the Claude adapter runs with `bypassPermissions` mode to enable non-interactive sub-agent execution. This means spawned Claude Code agents can execute tools without user confirmation. To change this behavior, set the `RELAY_CLAUDE_PERMISSION_MODE` environment variable to `default`.
+
 ## MCP Server Mode
 
 agentic-relay can act as an MCP (Model Context Protocol) server, allowing any MCP-capable client to spawn sub-agents across all three backends. This is how nested sub-agent orchestration works -- a parent agent calls relay via MCP, which spawns a child agent on any backend, and that child can call relay again to spawn a grandchild.
@@ -317,7 +321,7 @@ src/
 - **Process management**: execa (interactive modes, Gemini CLI)
 - **Validation**: zod
 - **Logging**: consola
-- **Testing**: vitest (507 tests across 28 files)
+- **Testing**: vitest (771 tests across 35 files)
 - **Coverage**: @vitest/coverage-v8
 
 ## License

package/dist/relay.mjs

@@ -159,7 +159,7 @@ var init_recursion_guard = __esm({
 import { z as z2 } from "zod";
 import { nanoid as nanoid2 } from "nanoid";
 import { existsSync, readFileSync } from "fs";
-import { join as join6 } from "path";
+import { join as join6, normalize, resolve, sep } from "path";
 function buildContextInjection(metadata) {
   const parts = [];
   if (metadata.stateContent && typeof metadata.stateContent === "string") {
@@ -190,15 +190,28 @@ function readPreviousState(dailynoteDir) {
     return null;
   }
 }
-function readAgentDefinition(definitionPath) {
+function validatePathWithinProject(filePath, projectRoot) {
+  if (filePath.trim().length === 0) {
+    throw new Error("Path is empty");
+  }
+  const normalizedProjectRoot = normalize(resolve(projectRoot));
+  const resolvedPath = normalize(resolve(normalizedProjectRoot, filePath));
+  const projectRootPrefix = normalizedProjectRoot.endsWith(sep) ? normalizedProjectRoot : `${normalizedProjectRoot}${sep}`;
+  if (resolvedPath !== normalizedProjectRoot && !resolvedPath.startsWith(projectRootPrefix)) {
+    throw new Error(`Path traversal detected: ${filePath}`);
+  }
+  return resolvedPath;
+}
+function readAgentDefinition(definitionPath, projectRoot = process.cwd()) {
   try {
-    if (!existsSync(definitionPath)) {
-      logger.warn(`Agent definition file not found at ${definitionPath}`);
+    const safeDefinitionPath = validatePathWithinProject(definitionPath, projectRoot);
+    if (!existsSync(safeDefinitionPath)) {
+      logger.warn(`Agent definition file not found at ${safeDefinitionPath}`);
       return null;
     }
-    const content = readFileSync(definitionPath, "utf-8");
+    const content = readFileSync(safeDefinitionPath, "utf-8");
     if (content.trim().length === 0) {
-      logger.warn(`Agent definition file is empty at ${definitionPath}`);
+      logger.warn(`Agent definition file is empty at ${safeDefinitionPath}`);
       return null;
     }
     return content;
@@ -209,9 +222,10 @@ function readAgentDefinition(definitionPath) {
     return null;
   }
 }
-function readSkillContext(skillContext) {
+function readSkillContext(skillContext, projectRoot = process.cwd()) {
   try {
-    const skillMdPath = join6(skillContext.skillPath, "SKILL.md");
+    const safeSkillPath = validatePathWithinProject(skillContext.skillPath, projectRoot);
+    const skillMdPath = validatePathWithinProject(join6(safeSkillPath, "SKILL.md"), projectRoot);
     if (!existsSync(skillMdPath)) {
       logger.warn(
         `SKILL.md not found at ${skillMdPath}`
@@ -222,12 +236,12 @@ function readSkillContext(skillContext) {
     const skillContent = readFileSync(skillMdPath, "utf-8");
     parts.push(skillContent);
     if (skillContext.subskill) {
-      const subskillPath = join6(
-        skillContext.skillPath,
+      const subskillPath = validatePathWithinProject(join6(
+        safeSkillPath,
         "subskills",
         skillContext.subskill,
         "SUBSKILL.md"
-      );
+      ), projectRoot);
       if (existsSync(subskillPath)) {
         const subskillContent = readFileSync(subskillPath, "utf-8");
         parts.push(subskillContent);
@@ -299,8 +313,10 @@ function buildContextFromEnv() {
   const depth = Number(process.env["RELAY_DEPTH"] ?? "0");
   return { traceId, parentSessionId, depth };
 }
-async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl) {
+async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress) {
+  onProgress?.({ stage: "initializing", percent: 0 });
   let effectiveBackend = input.backend;
+  let selectionReason = "direct";
   if (backendSelector) {
     const availableBackends = registry2.listIds();
     const selectionContext = {
@@ -309,7 +325,9 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       agentType: input.agent,
       taskType: input.taskType
     };
-    effectiveBackend = backendSelector.selectBackend(selectionContext);
+    const selectionResult = backendSelector.selectBackendWithReason(selectionContext);
+    effectiveBackend = selectionResult.backend;
+    selectionReason = selectionResult.reason;
   }
   const envContext = buildContextFromEnv();
   const promptHash = RecursionGuard.hashPrompt(input.prompt);
@@ -418,41 +436,91 @@ ${defText}
 ${wrapped}` : wrapped;
     }
   }
-  try {
-    let result;
-    if (input.resumeSessionId) {
-      if (!adapter.continueSession) {
+  let effectivePrompt = input.prompt;
+  if (input.taskInstructionPath) {
+    try {
+      const projectRoot = process.cwd();
+      const safePath = validatePathWithinProject(input.taskInstructionPath, projectRoot);
+      if (!existsSync(safePath)) {
         return {
-          sessionId: session.relaySessionId,
+          sessionId: "",
           exitCode: 1,
           stdout: "",
-          stderr: `Backend "${effectiveBackend}" does not support session continuation (continueSession).`
+          stderr: `Task instruction file not found: ${input.taskInstructionPath}`
         };
       }
-      result = await adapter.continueSession(input.resumeSessionId, input.prompt);
-    } else {
-      let mcpServers;
-      if (childHttpUrl) {
-        const parentMcpServers = readProjectMcpJson();
-        if (Object.keys(parentMcpServers).length > 0) {
-          mcpServers = buildChildMcpServers(parentMcpServers, childHttpUrl);
+      const instructionContent = readFileSync(safePath, "utf-8");
+      effectivePrompt = `${instructionContent}
+
+${input.prompt}`;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        sessionId: "",
+        exitCode: 1,
+        stdout: "",
+        stderr: `Failed to read task instruction file: ${message}`
+      };
+    }
+  }
+  onProgress?.({ stage: "spawning", percent: 10 });
+  try {
+    let result;
+    const executePromise = (async () => {
+      if (input.resumeSessionId) {
+        if (!adapter.continueSession) {
+          return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `Backend "${effectiveBackend}" does not support session continuation (continueSession).`,
+            _noSession: true
+          };
         }
+        return adapter.continueSession(input.resumeSessionId, effectivePrompt);
+      } else {
+        let mcpServers;
+        if (childHttpUrl) {
+          const parentMcpServers = readProjectMcpJson();
+          if (Object.keys(parentMcpServers).length > 0) {
+            mcpServers = buildChildMcpServers(parentMcpServers, childHttpUrl);
+          }
+        }
+        return adapter.execute({
+          prompt: effectivePrompt,
+          agent: input.agent,
+          systemPrompt: enhancedSystemPrompt,
+          model: input.model,
+          maxTurns: input.maxTurns,
+          mcpContext: {
+            parentSessionId: session.relaySessionId,
+            depth: envContext.depth + 1,
+            maxDepth: guard.getConfig().maxDepth,
+            traceId: envContext.traceId
+          },
+          ...mcpServers ? { mcpServers } : {}
+        });
       }
-      result = await adapter.execute({
-        prompt: input.prompt,
-        agent: input.agent,
-        systemPrompt: enhancedSystemPrompt,
-        model: input.model,
-        maxTurns: input.maxTurns,
-        mcpContext: {
-          parentSessionId: session.relaySessionId,
-          depth: envContext.depth + 1,
-          maxDepth: guard.getConfig().maxDepth,
-          traceId: envContext.traceId
-        },
-        ...mcpServers ? { mcpServers } : {}
-      });
+    })();
+    if (input.timeoutMs) {
+      const timeoutPromise = new Promise(
+        (_, reject) => setTimeout(
+          () => reject(new Error(`Agent execution timed out after ${input.timeoutMs}ms`)),
+          input.timeoutMs
+        )
+      );
+      result = await Promise.race([executePromise, timeoutPromise]);
+    } else {
+      result = await executePromise;
+    }
+    if (result && "_noSession" in result) {
+      return {
+        sessionId: session.relaySessionId,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr
+      };
     }
+    onProgress?.({ stage: "executing", percent: 50 });
     if (contextMonitor2) {
       const estimatedTokens = Math.ceil(
         (result.stdout.length + result.stderr.length) / 4
@@ -466,6 +534,16 @@ ${wrapped}` : wrapped;
     guard.recordSpawn(context);
     const status = result.exitCode === 0 ? "completed" : "error";
     await sessionManager2.update(session.relaySessionId, { status });
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const metadata = {
+      durationMs: new Date(completedAt).getTime() - new Date(spawnStartedAt).getTime(),
+      selectedBackend: effectiveBackend,
+      ...input.preferredBackend ? { requestedBackend: input.preferredBackend } : {},
+      selectionReason,
+      startedAt: spawnStartedAt,
+      completedAt
+    };
+    onProgress?.({ stage: "completed", percent: 100 });
     if (hooksEngine2) {
       try {
         const postSpawnData = {
@@ -502,7 +580,8 @@ ${wrapped}` : wrapped;
       exitCode: result.exitCode,
       stdout: result.stdout,
       stderr: result.stderr,
-      nativeSessionId: result.nativeSessionId
+      nativeSessionId: result.nativeSessionId,
+      metadata
     };
   } catch (error) {
     await sessionManager2.update(session.relaySessionId, { status: "error" });
@@ -537,11 +616,223 @@ var init_spawn_agent = __esm({
         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.")
+      taskType: z2.enum(["code", "document", "analysis", "mixed"]).optional().describe("Task type hint for automatic backend selection when preferredBackend is not specified."),
+      timeoutMs: z2.number().optional().describe("Timeout in milliseconds for agent execution. Default: no timeout."),
+      taskInstructionPath: z2.string().optional().describe(
+        "Path to a file containing task instructions. Content is prepended to the prompt. Path is resolved relative to the project root and validated against path traversal."
+      )
     });
   }
 });
 
+// src/mcp-server/tools/conflict-detector.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+async function takeSnapshot(cwd) {
+  try {
+    const [diffResult, lsResult] = await Promise.all([
+      execFileAsync("git", ["diff", "--name-only", "HEAD"], { cwd }).catch(() => ({ stdout: "" })),
+      execFileAsync("git", ["ls-files", "-m"], { cwd }).catch(() => ({ stdout: "" }))
+    ]);
+    const files = /* @__PURE__ */ new Set();
+    for (const line of diffResult.stdout.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed) files.add(trimmed);
+    }
+    for (const line of lsResult.stdout.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed) files.add(trimmed);
+    }
+    return files;
+  } catch (error) {
+    logger.warn(
+      `Failed to take git snapshot: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return /* @__PURE__ */ new Set();
+  }
+}
+function extractMentionedPaths(stdout) {
+  const paths = /* @__PURE__ */ new Set();
+  const patterns = [
+    /(?:^|\s|["'`])(\.\/.+?\.[a-zA-Z]{1,5})(?:\s|["'`]|$)/gm,
+    /(?:^|\s|["'`])(src\/.+?\.[a-zA-Z]{1,5})(?:\s|["'`]|$)/gm,
+    /(?:^|\s|["'`])([a-zA-Z][a-zA-Z0-9_-]*(?:\/[a-zA-Z0-9_.-]+){1,10}\.[a-zA-Z]{1,5})(?:\s|["'`]|$)/gm
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(stdout)) !== null) {
+      let path = match[1];
+      if (path.startsWith("./")) {
+        path = path.slice(2);
+      }
+      paths.add(path);
+    }
+  }
+  return paths;
+}
+async function detectConflicts(before, after, agentResults) {
+  const newlyModified = /* @__PURE__ */ new Set();
+  for (const file of after) {
+    if (!before.has(file)) {
+      newlyModified.add(file);
+    }
+  }
+  if (newlyModified.size === 0) {
+    return { conflicts: [], hasConflicts: false };
+  }
+  const agentPaths = /* @__PURE__ */ new Map();
+  for (const agent of agentResults) {
+    agentPaths.set(agent.index, extractMentionedPaths(agent.stdout));
+  }
+  const fileToAgents = /* @__PURE__ */ new Map();
+  for (const file of newlyModified) {
+    const matchingAgents = [];
+    for (const [index, paths] of agentPaths) {
+      for (const mentionedPath of paths) {
+        if (file === mentionedPath || file.endsWith(mentionedPath) || mentionedPath.endsWith(file)) {
+          matchingAgents.push(index);
+          break;
+        }
+      }
+    }
+    if (matchingAgents.length > 1) {
+      fileToAgents.set(file, matchingAgents);
+    }
+  }
+  const conflicts = Array.from(fileToAgents.entries()).map(
+    ([path, agents]) => ({ path, agents })
+  );
+  return {
+    conflicts,
+    hasConflicts: conflicts.length > 0
+  };
+}
+var execFileAsync;
+var init_conflict_detector = __esm({
+  "src/mcp-server/tools/conflict-detector.ts"() {
+    "use strict";
+    init_logger();
+    execFileAsync = promisify(execFile);
+  }
+});
+
+// src/mcp-server/tools/spawn-agents-parallel.ts
+async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress) {
+  const envContext = buildContextFromEnv();
+  if (envContext.depth >= guard.getConfig().maxDepth) {
+    const reason = `Max depth exceeded: ${envContext.depth} >= ${guard.getConfig().maxDepth}`;
+    logger.warn(`Batch spawn blocked by RecursionGuard: ${reason}`);
+    return {
+      results: agents.map((_, index) => ({
+        index,
+        sessionId: "",
+        exitCode: 1,
+        stdout: "",
+        stderr: `Batch spawn blocked: ${reason}`,
+        error: reason
+      })),
+      totalCount: agents.length,
+      successCount: 0,
+      failureCount: agents.length
+    };
+  }
+  const currentCount = guard.getCallCount(envContext.traceId);
+  const maxCalls = guard.getConfig().maxCallsPerSession;
+  if (currentCount + agents.length > maxCalls) {
+    const reason = `Batch would exceed max calls per session: ${currentCount} + ${agents.length} > ${maxCalls}`;
+    logger.warn(`Batch spawn blocked by RecursionGuard: ${reason}`);
+    return {
+      results: agents.map((_, index) => ({
+        index,
+        sessionId: "",
+        exitCode: 1,
+        stdout: "",
+        stderr: `Batch spawn blocked: ${reason}`,
+        error: reason
+      })),
+      totalCount: agents.length,
+      successCount: 0,
+      failureCount: agents.length
+    };
+  }
+  const cwd = process.cwd();
+  const beforeSnapshot = await takeSnapshot(cwd);
+  onProgress?.({ stage: "spawning", percent: 5 });
+  let completedCount = 0;
+  const settled = await Promise.allSettled(
+    agents.map(
+      (agent) => executeSpawnAgent(
+        agent,
+        registry2,
+        sessionManager2,
+        guard,
+        hooksEngine2,
+        contextMonitor2,
+        backendSelector,
+        childHttpUrl
+      ).then((result) => {
+        completedCount++;
+        onProgress?.({
+          stage: `completed ${completedCount}/${agents.length}`,
+          percent: Math.round(completedCount / agents.length * 90) + 5
+        });
+        return result;
+      })
+    )
+  );
+  const results = settled.map((outcome, index) => {
+    if (outcome.status === "fulfilled") {
+      const r = outcome.value;
+      const base = {
+        index,
+        sessionId: r.sessionId,
+        exitCode: r.exitCode,
+        stdout: r.stdout,
+        stderr: r.stderr,
+        ...r.nativeSessionId ? { nativeSessionId: r.nativeSessionId } : {},
+        ...r.metadata ? { metadata: r.metadata } : {}
+      };
+      if (r.exitCode !== 0) {
+        base.originalInput = agents[index];
+      }
+      return base;
+    }
+    const errorMessage = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+    return {
+      index,
+      sessionId: "",
+      exitCode: 1,
+      stdout: "",
+      stderr: errorMessage,
+      error: errorMessage,
+      originalInput: agents[index]
+    };
+  });
+  const successCount = results.filter((r) => r.exitCode === 0).length;
+  const afterSnapshot = await takeSnapshot(cwd);
+  const agentResultsForConflict = results.map((r) => ({
+    index: r.index,
+    stdout: r.stdout
+  }));
+  const conflictResult = await detectConflicts(beforeSnapshot, afterSnapshot, agentResultsForConflict);
+  onProgress?.({ stage: "completed", percent: 100 });
+  return {
+    results,
+    totalCount: agents.length,
+    successCount,
+    failureCount: agents.length - successCount,
+    ...conflictResult.hasConflicts ? { conflicts: conflictResult.conflicts, hasConflicts: true } : {}
+  };
+}
+var init_spawn_agents_parallel = __esm({
+  "src/mcp-server/tools/spawn-agents-parallel.ts"() {
+    "use strict";
+    init_spawn_agent();
+    init_conflict_detector();
+    init_logger();
+  }
+});
+
 // src/mcp-server/tools/list-sessions.ts
 import { z as z3 } from "zod";
 async function executeListSessions(input, sessionManager2) {
@@ -654,32 +945,35 @@ var init_backend_selector = __esm({
         this.agentToBackendMap = config?.agentToBackendMap ?? DEFAULT_AGENT_TO_BACKEND_MAP;
       }
       selectBackend(context) {
+        return this.selectBackendWithReason(context).backend;
+      }
+      selectBackendWithReason(context) {
         const { availableBackends, preferredBackend, agentType, taskType } = context;
         if (availableBackends.length === 0) {
           throw new Error("No backends available");
         }
         if (preferredBackend && availableBackends.includes(preferredBackend)) {
-          return preferredBackend;
+          return { backend: preferredBackend, reason: "preferredBackend" };
         }
         if (agentType) {
           const mapped = this.agentToBackendMap[agentType];
           if (mapped && availableBackends.includes(mapped)) {
-            return mapped;
+            return { backend: mapped, reason: `agentType:${agentType}\u2192${mapped}` };
           }
           if (!mapped && availableBackends.includes("claude")) {
-            return "claude";
+            return { backend: "claude", reason: `agentType:${agentType}\u2192claude(unmapped)` };
           }
         }
         if (taskType) {
           const mapped = TASK_TYPE_TO_BACKEND_MAP[taskType];
           if (mapped && availableBackends.includes(mapped)) {
-            return mapped;
+            return { backend: mapped, reason: `taskType:${taskType}\u2192${mapped}` };
           }
         }
         if (availableBackends.includes(this.defaultBackend)) {
-          return this.defaultBackend;
+          return { backend: this.defaultBackend, reason: "default" };
         }
-        return availableBackends[0];
+        return { backend: availableBackends[0], reason: "fallback" };
       }
     };
   }
@@ -696,17 +990,24 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { createServer } from "http";
 import { randomUUID } from "crypto";
 import { z as z5 } from "zod";
-var RelayMCPServer;
+var spawnAgentsParallelInputShape, MAX_CHILD_HTTP_SESSIONS, RelayMCPServer;
 var init_server = __esm({
   "src/mcp-server/server.ts"() {
     "use strict";
     init_recursion_guard();
     init_spawn_agent();
+    init_spawn_agents_parallel();
     init_list_sessions();
     init_get_context_status();
     init_list_available_backends();
     init_backend_selector();
     init_logger();
+    spawnAgentsParallelInputShape = {
+      agents: z5.array(spawnAgentInputSchema).min(1).max(10).describe(
+        "Array of agent configurations to execute in parallel (1-10 agents)"
+      )
+    };
+    MAX_CHILD_HTTP_SESSIONS = 100;
     RelayMCPServer = class {
       constructor(registry2, sessionManager2, guardConfig, hooksEngine2, contextMonitor2) {
         this.registry = registry2;
@@ -717,7 +1018,7 @@ var init_server = __esm({
         this.backendSelector = new BackendSelector();
         this.server = new McpServer({
           name: "agentic-relay",
-          version: "0.6.4"
+          version: "0.8.0"
         });
         this.registerTools(this.server);
       }
@@ -738,28 +1039,23 @@ var init_server = __esm({
         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), '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(),
-            agent: z5.string().optional().describe("Named agent configuration (Claude only)"),
-            systemPrompt: z5.string().optional().describe(
-              "System prompt / role instructions for the sub-agent (all backends)"
-            ),
-            resumeSessionId: z5.string().optional(),
-            model: z5.string().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) => {
+          spawnAgentInputSchema.shape,
+          async (params, extra) => {
             try {
+              const onProgress = (progress) => {
+                const progressToken = params._meta ? params._meta.progressToken : void 0;
+                if (progressToken !== void 0) {
+                  void extra.sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                      progressToken,
+                      progress: progress.percent ?? 0,
+                      total: 100,
+                      message: progress.stage
+                    }
+                  });
+                }
+              };
               const result = await executeSpawnAgent(
                 params,
                 this.registry,
@@ -768,12 +1064,110 @@ var init_server = __esm({
                 this.hooksEngine,
                 this.contextMonitor,
                 this.backendSelector,
-                this._childHttpUrl
+                this._childHttpUrl,
+                onProgress
               );
               const isError = result.exitCode !== 0;
-              const text = isError ? `Error (exit ${result.exitCode}): ${result.stderr || result.stdout}` : `Session: ${result.sessionId}
+              let text = isError ? `Error (exit ${result.exitCode}): ${result.stderr || result.stdout}` : `Session: ${result.sessionId}
 
 ${result.stdout}`;
+              if (result.metadata) {
+                text += `
+
+<metadata>
+${JSON.stringify(result.metadata, null, 2)}
+</metadata>`;
+              }
+              return {
+                content: [{ type: "text", text }],
+                isError
+              };
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true
+              };
+            }
+          }
+        );
+        server.tool(
+          "spawn_agents_parallel",
+          "Spawn multiple sub-agents in parallel across available backends. Each agent entry accepts the same parameters as spawn_agent. All agents are executed concurrently via Promise.allSettled, and results are returned as an array with per-agent status. RecursionGuard batch pre-validation ensures the entire batch fits within call limits before execution begins. Failed results include 'originalInput' for retry via retry_failed_agents.",
+          spawnAgentsParallelInputShape,
+          async (params, extra) => {
+            try {
+              const onProgress = (progress) => {
+                const progressToken = params._meta ? params._meta.progressToken : void 0;
+                if (progressToken !== void 0) {
+                  void extra.sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                      progressToken,
+                      progress: progress.percent ?? 0,
+                      total: 100,
+                      message: progress.stage
+                    }
+                  });
+                }
+              };
+              const result = await executeSpawnAgentsParallel(
+                params.agents,
+                this.registry,
+                this.sessionManager,
+                this.guard,
+                this.hooksEngine,
+                this.contextMonitor,
+                this.backendSelector,
+                this._childHttpUrl,
+                onProgress
+              );
+              const isError = result.failureCount === result.totalCount;
+              let text = "";
+              if (result.hasConflicts) {
+                text += "\u26A0 FILE CONFLICTS DETECTED: Multiple agents modified the same files.\n";
+                text += `Conflicting files: ${result.conflicts.map((c) => c.path).join(", ")}
+
+`;
+              }
+              text += JSON.stringify(result, null, 2);
+              return {
+                content: [{ type: "text", text }],
+                isError
+              };
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true
+              };
+            }
+          }
+        );
+        server.tool(
+          "retry_failed_agents",
+          "Retry only the failed agents from a previous spawn_agents_parallel call. Pass the failed results array (with originalInput) directly.",
+          {
+            failedResults: z5.array(z5.object({
+              index: z5.number(),
+              originalInput: spawnAgentInputSchema
+            })).min(1).describe("Array of failed results with their original input configurations")
+          },
+          async (params) => {
+            try {
+              const agents = params.failedResults.map((r) => r.originalInput);
+              const result = await executeSpawnAgentsParallel(
+                agents,
+                this.registry,
+                this.sessionManager,
+                this.guard,
+                this.hooksEngine,
+                this.contextMonitor,
+                this.backendSelector,
+                this._childHttpUrl
+              );
+              const isError = result.failureCount === result.totalCount;
+              const text = JSON.stringify(result, null, 2);
               return {
                 content: [{ type: "text", text }],
                 isError
@@ -899,14 +1293,14 @@ ${result.stdout}`;
         });
         this._httpServer = httpServer;
         await this.server.connect(httpTransport);
-        await new Promise((resolve) => {
-          httpServer.listen(port, () => {
+        await new Promise((resolve2) => {
+          httpServer.listen(port, "127.0.0.1", () => {
             logger.info(`MCP server listening on http://localhost:${port}/mcp`);
-            resolve();
+            resolve2();
           });
         });
-        await new Promise((resolve) => {
-          httpServer.on("close", resolve);
+        await new Promise((resolve2) => {
+          httpServer.on("close", resolve2);
         });
       }
       /**
@@ -937,7 +1331,7 @@ ${result.stdout}`;
           });
           const server = new McpServer({
             name: "agentic-relay",
-            version: "0.6.4"
+            version: "0.8.0"
           });
           this.registerTools(server);
           transport.onclose = () => {
@@ -953,15 +1347,31 @@ ${result.stdout}`;
           if (sid) {
             sessions.set(sid, { transport, server });
             logger.debug(`Child MCP session created: ${sid}`);
+            if (sessions.size > MAX_CHILD_HTTP_SESSIONS) {
+              const oldestEntry = sessions.entries().next().value;
+              if (oldestEntry) {
+                const [oldestSessionId, oldestSession] = oldestEntry;
+                sessions.delete(oldestSessionId);
+                logger.warn(
+                  `Child MCP session evicted due to limit (${MAX_CHILD_HTTP_SESSIONS}): ${oldestSessionId}`
+                );
+                void oldestSession.transport.close().catch((error) => {
+                  const message = error instanceof Error ? error.message : String(error);
+                  logger.debug(
+                    `Failed to close evicted child MCP session ${oldestSessionId}: ${message}`
+                  );
+                });
+              }
+            }
           }
         });
         this._childHttpServer = httpServer;
-        await new Promise((resolve) => {
+        await new Promise((resolve2) => {
           httpServer.listen(0, "127.0.0.1", () => {
             const addr = httpServer.address();
             this._childHttpUrl = `http://127.0.0.1:${addr.port}/mcp`;
             logger.info(`Child MCP server listening on ${this._childHttpUrl}`);
-            resolve();
+            resolve2();
           });
         });
       }
@@ -1113,10 +1523,11 @@ var AdapterRegistry = class {
 
 // src/adapters/base-adapter.ts
 init_logger();
-var BaseAdapter = class {
+var BaseAdapter = class _BaseAdapter {
   constructor(processManager2) {
     this.processManager = processManager2;
   }
+  static HEALTH_TIMEOUT_MS = 5e3;
   async isInstalled() {
     try {
       const result = await this.processManager.execute("which", [this.command]);
@@ -1144,11 +1555,13 @@ var BaseAdapter = class {
     };
   }
   async checkHealth() {
-    const HEALTH_TIMEOUT = 5e3;
     const installed = await Promise.race([
       this.isInstalled(),
       new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+        (_, reject) => setTimeout(
+          () => reject(new Error("timeout")),
+          _BaseAdapter.HEALTH_TIMEOUT_MS
+        )
       )
     ]).catch(() => false);
     if (!installed) {
@@ -1162,14 +1575,29 @@ var BaseAdapter = class {
     const version = await Promise.race([
       this.getVersion(),
       new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+        (_, reject) => setTimeout(
+          () => reject(new Error("timeout")),
+          _BaseAdapter.HEALTH_TIMEOUT_MS
+        )
       )
     ]).catch(() => void 0);
+    const authStatus = await Promise.race([
+      this.checkAuthStatus(),
+      new Promise(
+        (_, reject) => setTimeout(
+          () => reject(new Error("timeout")),
+          _BaseAdapter.HEALTH_TIMEOUT_MS
+        )
+      )
+    ]).catch(() => ({ authenticated: true }));
+    const authenticated = authStatus.authenticated;
+    const message = authStatus.message ?? (!authenticated ? `${this.id} authentication not configured` : void 0);
     return {
       installed: true,
-      authenticated: true,
-      healthy: true,
-      version
+      authenticated,
+      healthy: authenticated,
+      version,
+      ...message ? { message } : {}
     };
   }
   async getMCPConfig() {
@@ -1284,45 +1712,14 @@ var ClaudeAdapter = class extends BaseAdapter {
   getConfigPath() {
     return join(homedir(), ".claude.json");
   }
-  async checkHealth() {
-    const HEALTH_TIMEOUT = 5e3;
-    const installed = await Promise.race([
-      this.isInstalled(),
-      new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-      )
-    ]).catch(() => false);
-    if (!installed) {
-      return {
-        installed: false,
-        authenticated: false,
-        healthy: false,
-        message: "claude is not installed"
-      };
-    }
-    const version = await Promise.race([
-      this.getVersion(),
-      new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-      )
-    ]).catch(() => void 0);
-    let authenticated = true;
-    try {
-      const result = await Promise.race([
-        this.processManager.execute(this.command, ["auth", "status"]),
-        new Promise(
-          (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-        )
-      ]);
-      authenticated = result.exitCode === 0;
-    } catch {
-      authenticated = true;
-    }
+  async checkAuthStatus() {
+    const result = await this.processManager.execute(this.command, [
+      "auth",
+      "status"
+    ]);
+    const authenticated = result.exitCode === 0;
     return {
-      installed: true,
       authenticated,
-      healthy: authenticated,
-      version,
       ...!authenticated ? { message: "claude authentication not configured" } : {}
     };
   }
@@ -1761,48 +2158,32 @@ var CodexAdapter = class extends BaseAdapter {
   getConfigPath() {
     return join2(homedir2(), ".codex", "config.toml");
   }
-  async checkHealth() {
-    const HEALTH_TIMEOUT = 5e3;
-    const installed = await Promise.race([
-      this.isInstalled(),
-      new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-      )
-    ]).catch(() => false);
-    if (!installed) {
-      return {
-        installed: false,
-        authenticated: false,
-        healthy: false,
-        message: "codex is not installed"
-      };
-    }
-    const version = await Promise.race([
-      this.getVersion(),
-      new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-      )
-    ]).catch(() => void 0);
-    let authenticated = true;
-    try {
-      const result = await Promise.race([
-        this.processManager.execute(this.command, ["login", "status"]),
-        new Promise(
-          (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-        )
-      ]);
-      authenticated = result.exitCode === 0;
-    } catch {
-      authenticated = true;
-    }
+  async checkAuthStatus() {
+    const result = await this.processManager.execute(this.command, [
+      "login",
+      "status"
+    ]);
+    const authenticated = result.exitCode === 0;
     return {
-      installed: true,
       authenticated,
-      healthy: authenticated,
-      version,
       ...!authenticated ? { message: "codex authentication not configured" } : {}
     };
   }
+  buildCodexOptions(flags) {
+    if (!flags.mcpContext) {
+      return {};
+    }
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== void 0) {
+        env[key] = value;
+      }
+    }
+    env.RELAY_TRACE_ID = flags.mcpContext.traceId;
+    env.RELAY_PARENT_SESSION_ID = flags.mcpContext.parentSessionId;
+    env.RELAY_DEPTH = String(flags.mcpContext.depth);
+    return { env };
+  }
   mapFlags(flags) {
     const args = mapCommonToNative("codex", flags);
     if (flags.outputFormat === "json") {
@@ -1855,16 +2236,7 @@ ${prompt}`;
     );
     try {
       const { Codex } = await loadCodexSDK();
-      const codexOptions = {};
-      if (flags.mcpContext) {
-        codexOptions.env = {
-          ...process.env,
-          RELAY_TRACE_ID: flags.mcpContext.traceId,
-          RELAY_PARENT_SESSION_ID: flags.mcpContext.parentSessionId,
-          RELAY_DEPTH: String(flags.mcpContext.depth)
-        };
-      }
-      const codex = new Codex(codexOptions);
+      const codex = new Codex(this.buildCodexOptions(flags));
       const thread = codex.startThread({
         ...flags.model ? { model: flags.model } : {},
         workingDirectory: process.cwd(),
@@ -1896,16 +2268,7 @@ ${prompt}`;
     );
     try {
       const { Codex } = await loadCodexSDK();
-      const codexOptions = {};
-      if (flags.mcpContext) {
-        codexOptions.env = {
-          ...process.env,
-          RELAY_TRACE_ID: flags.mcpContext.traceId,
-          RELAY_PARENT_SESSION_ID: flags.mcpContext.parentSessionId,
-          RELAY_DEPTH: String(flags.mcpContext.depth)
-        };
-      }
-      const codex = new Codex(codexOptions);
+      const codex = new Codex(this.buildCodexOptions(flags));
       const thread = codex.startThread({
         ...flags.model ? { model: flags.model } : {},
         workingDirectory: process.cwd(),
@@ -1919,15 +2282,15 @@ ${prompt}`;
           threadId = event.thread_id;
         } else if (event.type === "item.started") {
           const item = event.item;
-          if (item?.type === "agent_message" && item.text) {
+          if (item.type === "agent_message" && item.text) {
             yield { type: "text", text: item.text };
-          } else if (item?.type === "command_execution") {
+          } else if (item.type === "command_execution") {
             yield {
               type: "tool_start",
               tool: item.command ?? "command",
               id: item.id ?? ""
             };
-          } else if (item?.type === "file_change") {
+          } else if (item.type === "file_change") {
             yield {
               type: "tool_start",
               tool: "file_change",
@@ -1936,17 +2299,17 @@ ${prompt}`;
           }
         } else if (event.type === "item.completed") {
           const item = event.item;
-          if (item?.type === "agent_message" && item.text) {
+          if (item.type === "agent_message" && item.text) {
             completedMessages.push(item.text);
             yield { type: "text", text: item.text };
-          } else if (item?.type === "command_execution") {
+          } else if (item.type === "command_execution") {
             yield {
               type: "tool_end",
               tool: item.command ?? "command",
               id: item.id ?? "",
               result: item.aggregated_output
             };
-          } else if (item?.type === "file_change") {
+          } else if (item.type === "file_change") {
             yield {
               type: "tool_end",
               tool: "file_change",
@@ -1969,7 +2332,7 @@ ${prompt}`;
             nativeSessionId: threadId ?? thread.id ?? void 0
           };
         } else if (event.type === "turn.failed") {
-          const errorMessage = event.error?.message ?? "Turn failed";
+          const errorMessage = event.error.message ?? "Turn failed";
           yield {
             type: "done",
             result: { exitCode: 1, stdout: "", stderr: errorMessage },
@@ -2106,37 +2469,18 @@ var GeminiAdapter = class extends BaseAdapter {
   getConfigPath() {
     return join3(homedir3(), ".gemini", "settings.json");
   }
-  async checkHealth() {
-    const HEALTH_TIMEOUT = 5e3;
-    const installed = await Promise.race([
-      this.isInstalled(),
-      new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-      )
-    ]).catch(() => false);
-    if (!installed) {
+  async checkAuthStatus() {
+    const hasApiKey = !!process.env["GEMINI_API_KEY"];
+    const hasGoogleAdc = !!process.env["GOOGLE_APPLICATION_CREDENTIALS"] || !!process.env["CLOUDSDK_CONFIG"];
+    const authenticated = hasApiKey || hasGoogleAdc;
+    if (!authenticated) {
       return {
-        installed: false,
-        authenticated: false,
-        healthy: false,
-        message: "gemini is not installed"
+        // Optimistic fallback: Gemini may still authenticate via ADC at runtime.
+        authenticated: true,
+        message: "Gemini authentication status unknown - ADC may be available at runtime"
       };
     }
-    const version = await Promise.race([
-      this.getVersion(),
-      new Promise(
-        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
-      )
-    ]).catch(() => void 0);
-    const hasApiKey = !!process.env["GEMINI_API_KEY"];
-    const hasGoogleAdc = !!process.env["GOOGLE_APPLICATION_CREDENTIALS"] || !!process.env["CLOUDSDK_CONFIG"];
-    const authenticated = hasApiKey || hasGoogleAdc || true;
-    return {
-      installed: true,
-      authenticated,
-      healthy: true,
-      version
-    };
+    return { authenticated };
   }
   mapFlags(flags) {
     const args = mapCommonToNative("gemini", flags);
@@ -3025,6 +3369,7 @@ var HooksEngine = class _HooksEngine {
 };
 
 // src/core/context-monitor.ts
+init_logger();
 var DEFAULT_BACKEND_CONTEXT = {
   claude: { contextWindow: 2e5, compactThreshold: 19e4 },
   codex: { contextWindow: 272e3, compactThreshold: 258400 },
@@ -3143,7 +3488,9 @@ var ContextMonitor = class {
           remainingBeforeCompact
         }
       };
-      void this.hooksEngine.emit("on-context-threshold", hookInput);
+      void this.hooksEngine.emit("on-context-threshold", hookInput).catch(
+        (e) => logger.debug("Context threshold hook error:", e)
+      );
     }
   }
 };
@@ -3919,7 +4266,7 @@ function createVersionCommand(registry2) {
       description: "Show relay and backend versions"
     },
     async run() {
-      const relayVersion = "0.6.4";
+      const relayVersion = "0.8.0";
       console.log(`agentic-relay v${relayVersion}`);
       console.log("");
       console.log("Backends:");
@@ -3946,9 +4293,9 @@ import { defineCommand as defineCommand8 } from "citty";
 import { access, constants, readdir as readdir2 } from "fs/promises";
 import { join as join7 } from "path";
 import { homedir as homedir5 } from "os";
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
 async function checkNodeVersion() {
   const version = process.version;
   const major = Number(version.slice(1).split(".")[0]);
@@ -4048,7 +4395,7 @@ async function checkMCPServerCommands(configManager2) {
     for (const [name, server] of Object.entries(mcpServers)) {
       const command = server.command;
       try {
-        await execFileAsync("which", [command]);
+        await execFileAsync2("which", [command]);
         results.push({
           label: `MCP server: ${name}`,
           ok: true,
@@ -4244,6 +4591,7 @@ function createInitCommand() {
 }
 
 // src/bin/relay.ts
+init_logger();
 var processManager = new ProcessManager();
 var registry = new AdapterRegistry();
 registry.registerLazy("claude", () => new ClaudeAdapter(processManager));
@@ -4264,12 +4612,11 @@ void configManager.getConfig().then((config) => {
   if (config.contextMonitor) {
     contextMonitor = new ContextMonitor(hooksEngine, config.contextMonitor);
   }
-}).catch(() => {
-});
+}).catch((e) => logger.debug("Config load failed:", e));
 var main = defineCommand10({
   meta: {
     name: "relay",
-    version: "0.6.4",
+    version: "0.8.0",
     description: "Unified CLI proxy for Claude Code, Codex CLI, and Gemini CLI"
   },
   subCommands: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rk0429/agentic-relay",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "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",
@@ -40,7 +40,9 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit",
+    "lint": "tsc --noEmit && eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "prepublishOnly": "pnpm test && pnpm build"
   },
   "engines": {
@@ -57,10 +59,15 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^25.3.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
     "tsup": "^8.4.0",
     "typescript": "^5.7.3",
+    "typescript-eslint": "^8.56.1",
     "vitest": "^3.0.7"
   },
   "pnpm": {