fix(code): fix subagent sessions

Author: adboio

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,
             },
           },
         });

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) => {

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),
+        ],
       },
     ],
   };