fix(code): fix subagent sessions

adboio · adboio · commit fbe83557a022 · 2026-04-03T14:31:58.000-07:00
diff --git a/apps/code/src/main/services/agent/service.ts b/apps/code/src/main/services/agent/service.ts
@@ -178,6 +178,56 @@ const onAgentLog: OnLogCallback = (level, scope, message, data) => {
   }
 };
 
+const HAIKU_EXPLORE_AGENT_OVERRIDE = {
+  description:
+    'Fast agent for exploring and understanding codebases. Use this when you need to find files by pattern (eg. "src/components/**/*.tsx"), search for code or keywords (eg. "where is the auth middleware?"), or answer questions about how the codebase works (eg. "how does the session service handle reconnects?"). When calling this agent, specify a thoroughness level: "quick" for targeted lookups, "medium" for broader exploration, or "very thorough" for comprehensive analysis across multiple locations.',
+  model: "haiku",
+  prompt: `You are a fast, read-only codebase exploration agent.
+
+Your job is to find files, search code, read the most relevant sources, and report findings clearly.
+
+Rules:
+- Never create, modify, delete, move, or copy files.
+- Never use shell redirection or any command that changes system state.
+- Use Glob for broad file pattern matching.
+- Use Grep for searching file contents.
+- Use Read when you know the exact file path to inspect.
+- Use Bash only for safe read-only commands like ls, git status, git log, git diff, find, cat, head, and tail.
+- Adapt your search approach based on the thoroughness level specified by the caller.
+- Return file paths as absolute paths in your final response.
+- Avoid using emojis.
+- Wherever possible, spawn multiple parallel tool calls for grepping and reading files.
+- Search efficiently, then read only the most relevant files.
+- Return findings directly in your final response — do not create files.`,
+  tools: [
+    "Bash",
+    "Glob",
+    "Grep",
+    "Read",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TodoWrite",
+  ],
+};
+
+function buildClaudeCodeOptions(args: {
+  additionalDirectories?: string[];
+  effort?: EffortLevel;
+  plugins: { type: "local"; path: string }[];
+}) {
+  return {
+    ...(args.additionalDirectories?.length && {
+      additionalDirectories: args.additionalDirectories,
+    }),
+    ...(args.effort && { effort: args.effort }),
+    plugins: args.plugins,
+    agents: {
+      "ph-explore": HAIKU_EXPLORE_AGENT_OVERRIDE,
+    },
+  };
+}
+
 interface SessionConfig {
   taskId: string;
   taskRunId: string;
@@ -631,6 +681,11 @@ When creating pull requests, add the following footer at the end of the PR descr
         },
         ...externalPlugins,
       ];
+      const claudeCodeOptions = buildClaudeCodeOptions({
+        additionalDirectories,
+        effort,
+        plugins,
+      });
 
       let configOptions: SessionConfigOption[] | undefined;
       let agentSessionId: string;
@@ -679,13 +734,7 @@ When creating pull requests, add the following footer at the end of the PR descr
             ...(permissionMode && { permissionMode }),
             ...(model != null && { model }),
             claudeCode: {
-              options: {
-                ...(additionalDirectories?.length && {
-                  additionalDirectories,
-                }),
-                ...(effort && { effort }),
-                plugins,
-              },
+              options: claudeCodeOptions,
             },
           },
         });
@@ -712,11 +761,7 @@ When creating pull requests, add the following footer at the end of the PR descr
             ...(permissionMode && { permissionMode }),
             ...(model != null && { model }),
             claudeCode: {
-              options: {
-                ...(additionalDirectories?.length && { additionalDirectories }),
-                ...(effort && { effort }),
-                plugins,
-              },
+              options: claudeCodeOptions,
             },
           },
         });
diff --git a/apps/code/src/main/services/auth-proxy/service.ts b/apps/code/src/main/services/auth-proxy/service.ts
@@ -154,13 +154,111 @@ export class AuthProxyService {
       req.on("data", (chunk: Buffer) => chunks.push(chunk));
       req.on("end", () => {
         fetchOptions.body = Buffer.concat(chunks);
+        this.logRequestBodySummary(fetchOptions.body as Buffer);
         this.forwardRequest(targetUrl.toString(), fetchOptions, res);
       });
     } else {
       this.forwardRequest(targetUrl.toString(), fetchOptions, res);
     }
   }
 
+  private logRequestBodySummary(body: Buffer): void {
+    try {
+      const json = JSON.parse(body.toString("utf-8"));
+      const totalBodyBytes = body.byteLength;
+
+      // Summarize system prompt
+      const system = json.system;
+      let systemSummary: unknown;
+      if (typeof system === "string") {
+        systemSummary = {
+          type: "string",
+          charLength: system.length,
+          preview: system.slice(0, 300),
+        };
+      } else if (Array.isArray(system)) {
+        systemSummary = system.map(
+          (block: Record<string, unknown>, i: number) => {
+            const text = block.text as string | undefined;
+            return {
+              index: i,
+              type: block.type,
+              cacheControl: block.cache_control,
+              charLength: text?.length ?? 0,
+              preview: text?.slice(0, 200),
+              tail: (text?.length ?? 0) > 200 ? text?.slice(-100) : undefined,
+            };
+          },
+        );
+      }
+
+      // Summarize messages
+      const messages = json.messages;
+      const messageSummary = Array.isArray(messages)
+        ? messages.map((msg: Record<string, unknown>, i: number) => {
+            const content = msg.content;
+            if (typeof content === "string") {
+              return {
+                index: i,
+                role: msg.role,
+                type: "string",
+                charLength: content.length,
+                preview: content.slice(0, 200),
+              };
+            }
+            if (Array.isArray(content)) {
+              return {
+                index: i,
+                role: msg.role,
+                blocks: content.map((block: Record<string, unknown>) => {
+                  const text = (block.text ?? block.content) as
+                    | string
+                    | undefined;
+                  return {
+                    type: block.type,
+                    ...(block.name ? { name: block.name } : {}),
+                    ...(block.tool_use_id
+                      ? { toolUseId: block.tool_use_id }
+                      : {}),
+                    cacheControl: block.cache_control,
+                    charLength: text?.length ?? 0,
+                    ...(text ? { preview: text.slice(0, 200) } : {}),
+                  };
+                }),
+              };
+            }
+            return { index: i, role: msg.role, type: typeof content };
+          })
+        : [];
+
+      // Summarize tools
+      const tools = json.tools;
+      const toolsSummary = Array.isArray(tools)
+        ? {
+            count: tools.length,
+            names: tools.map((t: Record<string, unknown>) => t.name),
+          }
+        : undefined;
+
+      log.info("API request body summary", {
+        totalBodyBytes,
+        model: json.model,
+        maxTokens: json.max_tokens,
+        systemBlockCount: Array.isArray(system)
+          ? system.length
+          : system
+            ? 1
+            : 0,
+        systemSummary,
+        messageCount: Array.isArray(messages) ? messages.length : 0,
+        messageSummary,
+        toolsSummary,
+      });
+    } catch {
+      // Best-effort logging, don't break the proxy
+    }
+  }
+
   private async forwardRequest(
     url: string,
     options: RequestInit,
diff --git a/packages/agent/src/adapters/claude/claude-agent.ts b/packages/agent/src/adapters/claude/claude-agent.ts
@@ -67,7 +67,6 @@ import {
   getEffortOptions,
   resolveModelPreference,
   supports1MContext,
-  supportsMcpInjection,
   toSdkModelId,
 } from "./session/models";
 import {
@@ -781,6 +780,16 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     const meta = params._meta as NewSessionMeta | undefined;
     const taskId = meta?.persistence?.taskId;
     const effort = meta?.claudeCode?.options?.effort as EffortLevel | undefined;
+    const agentOverrides = meta?.claudeCode?.options?.agents as
+      | Record<
+          string,
+          {
+            model?: string;
+            tools?: string[];
+            disallowedTools?: string[];
+          }
+        >
+      | undefined;
 
     // We want to create a new session id unless it is resume,
     // but not resume + forkSession.
@@ -798,18 +807,23 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     const settingsManager = new SettingsManager(cwd);
     await settingsManager.initialize();
 
-    const earlyModelId =
-      settingsManager.getSettings().model || meta?.model || "";
-    const mcpServers = supportsMcpInjection(earlyModelId)
-      ? parseMcpServers(params)
-      : {};
+    const mcpServers = parseMcpServers(params);
     const systemPrompt = buildSystemPrompt(meta?.systemPrompt);
 
     this.logger.info(isResume ? "Resuming session" : "Creating new session", {
       sessionId,
       taskId,
       taskRunId: meta?.taskRunId,
       cwd,
+      hasAgentOverrides: !!agentOverrides,
+      agentOverrideNames: agentOverrides ? Object.keys(agentOverrides) : [],
+      exploreOverride: agentOverrides?.Explore
+        ? {
+            model: agentOverrides.Explore.model,
+            tools: agentOverrides.Explore.tools,
+            disallowedTools: agentOverrides.Explore.disallowedTools,
+          }
+        : undefined,
     });
 
     const permissionMode: CodeExecutionMode =
diff --git a/packages/agent/src/adapters/claude/hooks.ts b/packages/agent/src/adapters/claude/hooks.ts
@@ -71,6 +71,56 @@ export const createPostToolUseHook =
     return { continue: true };
   };
 
+/**
+ * Rewrites Agent tool calls targeting built-in subagent types to use our custom
+ * definitions instead. This works around a Claude Agent SDK bug where
+ * `options.agents` cannot override built-in agent definitions because the
+ * built-ins appear first in the agents array and `Array.find()` returns the
+ * first match.
+ *
+ * By giving our custom agent a different name (e.g. "ph-explore") and rewriting
+ * the subagent_type in the tool input, we sidestep the collision entirely.
+ *
+ * https://github.com/anthropics/claude-agent-sdk-typescript/issues/267
+ */
+const SUBAGENT_REWRITES: Record<string, string> = {
+  Explore: "ph-explore",
+};
+
+export const createSubagentRewriteHook =
+  (logger: Logger): HookCallback =>
+  async (input: HookInput, _toolUseID: string | undefined) => {
+    if (input.hook_event_name !== "PreToolUse") {
+      return { continue: true };
+    }
+
+    if (input.tool_name !== "Agent") {
+      return { continue: true };
+    }
+
+    const toolInput = input.tool_input as Record<string, unknown> | undefined;
+    const subagentType = toolInput?.subagent_type;
+    if (typeof subagentType !== "string" || !SUBAGENT_REWRITES[subagentType]) {
+      return { continue: true };
+    }
+
+    const target = SUBAGENT_REWRITES[subagentType];
+    logger.info(
+      `[SubagentRewriteHook] Rewriting subagent_type: ${subagentType} → ${target}`,
+    );
+
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse" as const,
+        updatedInput: {
+          ...toolInput,
+          subagent_type: target,
+        },
+      },
+    };
+  };
+
 export const createPreToolUseHook =
   (settingsManager: SettingsManager, logger: Logger): HookCallback =>
   async (input: HookInput, _toolUseID: string | undefined) => {
diff --git a/packages/agent/src/adapters/claude/session/options.ts b/packages/agent/src/adapters/claude/session/options.ts
@@ -14,6 +14,7 @@ import type { Logger } from "../../../utils/logger";
 import {
   createPostToolUseHook,
   createPreToolUseHook,
+  createSubagentRewriteHook,
   type OnModeChange,
 } from "../hooks";
 import type { CodeExecutionMode } from "../tools";
@@ -117,7 +118,10 @@ function buildHooks(
     PreToolUse: [
       ...(userHooks?.PreToolUse || []),
       {
-        hooks: [createPreToolUseHook(settingsManager, logger)],
+        hooks: [
+          createPreToolUseHook(settingsManager, logger),
+          createSubagentRewriteHook(logger),
+        ],
       },
     ],
   };
