anthropics / anthropics/claude-agent-sdk-typescript
Bug: subagent definition overrides are ignored; large MCP tools break Haiku in Claude Code
- Dominant language
- Shell
- Stars
- 1.8k
- Forks
- 226
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
Overrides to built-in subagent definitions (like `Explore`) are ultimately ignored by the SDK.
The [docs](https://platform.claude.com/docs/en/agent-sdk/subagents#programmatic-definition-recommended) seem to indicate this is supported.
## Steps to reproduce
See [this commit](https://github.com/PostHog/code/commit/cd728404cc02d5cbced8a9d13cfdc4a044650534#diff-a675638fa5cb6c05cf47135381170cd39fd355635c8175cebd796a185fc3d339) for our attempted implementation, which does not work without [this SDK patch](https://github.com/PostHog/code/commit/cd728404cc02d5cbced8a9d13cfdc4a044650534#diff-b4202172912460fce00bd94c22b3c723e8c853ca2dcb496ac1a670ed5fd36446).
Without the patch:
- Override seems to be applied in sessions at init time
- `Explore` agents are still spawned with the default configuration
With the patch, `Explore` agents are spawned with our overridden configuration.
## Root cause
From what I (and Claude) can tell from the minified source:
- There's an initialize handler that is pre-populated with the built-in agent definitions, including `Explore`
- When custom agents exist in `options.agents`, they are _appended_ to this array via `.push(...)`
- When the `Agent` tool resolves a `subagent_type`, it uses `Array.find()` which returns **the first match**
- The first match is the built-in definition, not the override, so the built-in definition is always used
## Attempted workarounds
- [Rewriting tool calls to `Explore` agent to a different sub-agent that we define](https://github.com/PostHog/code/pull/1464/changes#diff-046fb282fa4bdac708a5d52eaa2d682ebb8a4bc7a0836a21940f7ecfbe502375) - this is probably what we'll do
- [Patching the SDK](https://github.com/PostHog/code/commit/cd728404cc02d5cbced8a9d13cfdc4a044650534#diff-b4202172912460fce00bd94c22b3c723e8c853ca2dcb496ac1a670ed5fd36446) - works, prefer not to do this for obvious reasons
- [Global subagent model override](https://github.com/PostHog/code/pull/1465) - also works, but downgrades subagents that would otherwise inherit parent session's model
- Rewriting all model requests from Haiku -> Sonnet (would be more expensive, slower)
## Impact
If a user has MCP tools that approach or surpass 200k tokens, standalone Haiku (and Haiku subagents, like the default `Explore` agent) are severely degraded or entirely broken. With no way to override sub-agent behavior, there's nothing we can do.
This issue exists in our implementation, **and in Claude Code**.
**Context:**
- Explore agents run on Haiku by default
- Haiku does not support tool search
- Therefore, all tools definitions are loaded into the sub-agent's context immediately
- If tool definitions push context to near or over 200k, the sub-agent either spins its wheels compacting constantly, or fails immediately
**Same behavior in Claude Code:**
Opus default Explore agent | Other Haiku subagents | Plain Haiku
-- | -- | --
|
|
These always fail | These always fail | Standalone Haiku is entirely broken
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.