Agent SDK: Subagent delegation broken in query() mode — pinned to v0.2.51 pending upstream fix

[Number531]

Summary

The Claude Agent SDK's Agent tool (formerly Task) was broken in query() mode starting from v0.2.63+. Resolved: SDK upgraded to 0.2.70 in commit a79e43a (2026-03-08). Subagent delegation is working. Defensive allowedTools added in commit 49dc024.

This issue now tracks remaining validation items from the original upgrade plan.

Current State (2026-03-10)

• SDK version: @anthropic-ai/claude-agent-sdk@0.2.70 (no longer pinned to 0.2.51)
• Subagent delegation: ✅ Working — model finds and uses Task tool via agentQuery()
• allowedTools: Defensive array includes both Task and Agent for name instability resilience
• Full analysis: docs/pending-updates/0.2.47-0.2.70-update.md

Resolved Items

• Phase 1: Monitor upstream Issue Roadmap: Incremental MCP → executable Python tool conversion (flat-registry; after orchestrator wrap) #210 — fixed in 0.2.70
• Phase 3: Bump SDK version — commit a79e43a
• Phase 3: Remove duplicate run_python_analysis registration guard — verified
• Phase 3: Update MEMORY.md — updated

Remaining Validation (narrowed scope)

• Effort override (feat(skills): add deep-plan + super-plan planning skills #214): Verify effort: 'high' is not silently overridden to medium by SDK 0.2.70. Our orchestrator sets effort: 'high' in agentQuery() (claude-sdk-server.js line 1157). Upstream #214 reported SDK 0.2.68+ may downgrade this.
• Hook native fields: Verify hook events carry agent_id/agent_type natively (v0.2.69 feature) — currently using string-matching heuristics in classifyAgent() (hookSSEBridge.js:16-64). If native fields are present, simplify classifyAgent().
• MCP disconnect: Verify no MCP server disconnects during long runs (29-subagent memo generation). This was a known issue in pre-0.2.69 versions.

Files Involved

File	Relevance
package.json:50	SDK version (now 0.2.70)
src/server/claude-sdk-server.js:1151-1199	agentQuery() with agents and allowedTools
src/utils/hookSSEBridge.js:16-64	classifyAgent() — can simplify if native fields available
docs/pending-updates/0.2.47-0.2.70-update.md	Full upgrade analysis

References

• Upstream: anthropics/claude-agent-sdk-typescript#210 (resolved)
• Upstream: anthropics/claude-agent-sdk-typescript#214 (open — effort override)
• Upgrade commit: a79e43a
• Defensive allowedTools commit: 49dc024

[Number531]

Update: Defensive allowedTools fix applied (v4.1.1, commit 49dc024)

Status: Partial mitigation shipped. SDK pin to v0.2.51 remains in place.

What was done

Per Anthropic subagent docs: "The Task tool must be included in allowedTools since Claude invokes subagents through the Task tool."

Our agentQuery() call omitted both allowedTools and tools parameters, leaving delegation availability to SDK defaults — which proved unreliable on v0.2.70 (Run 1: zero SubagentStart events, model did all research directly).

Fix: Added allowedTools: ORCHESTRATOR_ALLOWED_TOOLS to agentQuery() options. The list includes both "Task" and "Agent" to handle the SDK tool name instability documented in this issue (v0.2.44: Task, ~v0.2.50s: Agent, v0.2.69+: Task). Per the SDK reference, allowedTools is additive — extra entries are harmless.

Also added a startup diagnostic that logs delegation tool presence at system:init:

• ✅ [AgentSDK] Delegation tool "Task" confirmed (N tools) — healthy
• ⚠️ [AgentSDK] CRITICAL: No "Task" or "Agent" tool in system:init — actionable error

What this does NOT change

• SDK version pin remains at 0.2.51 — the upstream query() mode bug (Roadmap: Incremental MCP → executable Python tool conversion (flat-registry; after orchestrator wrap) #210) and effort override regression (feat(skills): add deep-plan + super-plan planning skills #214) are still unresolved
• permissionMode: 'bypassPermissions' still active — allowedTools is belt-and-suspenders
• No changes to subagent tool scoping, hook dispatch, or MCP server config

Remaining items on this issue

All Phase 1–3 remediation items from the issue body remain open. This fix makes delegation more robust on v0.2.51 and provides diagnostic logging for when we eventually test SDK upgrades.

Files changed

File	Change
src/config/legalSubagents/_standardTools.js	New ORCHESTRATOR_ALLOWED_TOOLS export
src/server/claude-sdk-server.js	Import, allowedTools param, delegation diagnostic, constraint #8
CHANGELOG.md	v4.1.1 entry

[Number531]

Update: SDK upgraded to 0.2.70 (commit a79e43a)

Rationale

The v0.2.51 pin (commit 7f16be3) was overly cautious. Evidence:

• Production run on v0.2.70 produced 30 SubagentStart events with full delegation
• Run 1's failure was caused by duplicate run_python_analysis registration (fixed in 1519db4), not an SDK bug
• The allowedTools fix from 49dc024 adds further hardening

Issue #214 (effort override) — confirmed non-impacting

Analyzed the minified CLI source in v0.2.70. The effort resolution precedence is:

env var (CLAUDE_CODE_EFFORT_LEVEL) → --effort CLI flag → tengu_turtle_carbon default

Our effort: 'high' is passed by the SDK as --effort high CLI flag, which takes priority over the feature flag's "medium" default. Added startup diagnostic to log effort level at system:init for ongoing verification.

Issue #210 (Agent tool broken in query mode) — resolved

The "Unknown tool: Agent" error was caused by duplicate run_python_analysis tool registration colliding with the SDK's internal tool table. Fixed in 1519db4. Not an SDK regression.

Status

• allowedTools fix (v4.1.1, 49dc024)
• SDK upgrade 0.2.51 → 0.2.70 (a79e43a)
• Effort diagnostic at startup
• Delegation diagnostic at startup
• Monitor for any regressions in next production run

[Number531]

Resolved — closing. See CHANGELOG for details.