feat(sdk): add sub-agent support to Python SDK and maxSubagentDepth to both SDKs

[juhuan]

Summary

Python SDK — add full sub-agent support:

• SubagentConfig and RunConfig TypedDicts
• agents option in QueryOptions (sent to CLI via initialize control request payload)
• max_subagent_depth option (maps to --max-subagent-depth CLI flag, validated 1–100)
• Validates each agent config requires name, description, and systemPrompt

TypeScript SDK — add maxSubagentDepth:

• maxSubagentDepth in TransportOptions, QueryOptions, and Zod schema (int, 1–100)
• Passed through createQuery → ProcessTransport → buildCliArguments as --max-subagent-depth
• The TS SDK already had agents support via SubagentConfig and the initialize payload

Test plan

• Python SDK tests pass (pytest — 58 passed)
• TypeScript SDK typecheck passes (tsc --noEmit)
• TypeScript SDK tests pass (vitest run — 1163 passed)
• Manual: verify agents config is received by CLI
• Manual: verify --max-subagent-depth limits nesting

[qwen-code-ci-bot]

Thanks for the PR!

Template: uses "Summary" / "Test plan" instead of the standard template headings ("What this PR does", "Why it's needed", "Reviewer Test Plan", "Risk & Scope", "Linked Issues"). Content is clear, but worth aligning with the template for future PRs.

Problem: this is a feature addition — exposing agents config in the Python SDK and maxSubagentDepth in both SDKs, wiring through to existing CLI flags and the initialize control request. No bug to reproduce; the gap is real (Python SDK had no way to configure sub-agents).

Direction: aligns with the project's sub-agent / multi-agent roadmap. The CLI already supports --max-subagent-depth and agents in the initialize payload — the SDKs were behind. This closes that gap.

Size: 92 additions, 0 deletions, 8 files. All in packages/sdk-python/ and packages/sdk-typescript/ — no core paths touched. Clean.

Approach: minimal and focused. Each change is a direct wire-through: type definition → validation → CLI arg / initialize payload. No over-abstraction, no scope creep. One minor note: the Python SubagentConfig TypedDict is defined but QueryOptions.agents is typed as list[dict[str, Any]] — slightly loose, but consistent with Python TypedDict limitations at runtime.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板：使用了 "Summary" / "Test plan" 而非标准模板标题（"What this PR does"、"Why it's needed"、"Reviewer Test Plan"、"Risk & Scope"、"Linked Issues"）。内容清晰，但建议后续 PR 对齐模板格式。

问题：这是功能新增——在 Python SDK 中暴露 agents 配置，在两个 SDK 中暴露 maxSubagentDepth，接入已有的 CLI 参数和 initialize 控制请求。没有 bug 需要复现；缺口是真实存在的（Python SDK 无法配置子代理）。

方向：与项目的子代理 / 多代理路线图一致。CLI 已经支持 --max-subagent-depth 和 initialize 中的 agents——SDK 落后了，这个 PR 补上了差距。

规模：92 行新增，0 行删除，8 个文件。全部在 packages/sdk-python/ 和 packages/sdk-typescript/ 中——未触及核心路径。干净。

方案：最小化且聚焦。每处改动都是直接贯通：类型定义 → 校验 → CLI 参数 / initialize payload。无过度抽象，无范围蔓延。一个小注：Python 的 SubagentConfig TypedDict 已定义但 QueryOptions.agents 类型为 list[dict[str, Any]]——稍显宽松，但与 Python TypedDict 运行时限制一致。

进入代码审查 🔍

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

2a. Code Review

The diff is clean and focused — each change is a direct wire-through from SDK types to CLI args / initialize payload. No correctness bugs, no security issues, no over-abstraction.

One gap worth noting: the PR adds new validation logic (max_subagent_depth range check, agents required-field checks) but includes no tests for these new code paths in either SDK. The existing 1163 TS / 58 Python tests all pass, but none exercise the new options. Adding tests for the validation and CLI argument generation would strengthen confidence — especially since the validation has several branches (bool rejection, range bounds, missing fields per agent).

Otherwise, the implementation follows project conventions well:

• TS: type added to TransportOptions + QueryOptions, schema validated with Zod, passed through createQuery → ProcessTransport → buildCliArguments.
• Python: TypedDict types defined, QueryOptions dataclass extended, _as_optional_list_of_dicts helper follows the existing pattern, validation mirrors the TS Zod constraints.

2b. Real-Scenario Testing

SDK test suites (worktree, PR diff applied):

TS SDK:   27 test files, 1163 tests passed ✓
Python SDK: 58 tests passed ✓

Manual validation probe (Python SDK, tmux):

$ PYTHONPATH=src python3 -c "..."
PASS: max_subagent_depth must be between 1 and 100   (rejected 0)
PASS: max_subagent_depth must be between 1 and 100   (rejected 101)
PASS: 5 accepted
PASS: agents[0] must have a non-empty 'description'  (rejected incomplete)
PASS: valid agent accepted

All five validation cases behave correctly.

CLI integration: could not run npm run dev (missing tsx in CI environment). Confirmed via code inspection that --max-subagent-depth is defined in packages/cli/src/config/config.ts:903 with integer validation and range clamping — the SDK passes it through correctly.

TUI: N/A — SDK-only changes, no user-visible output.

中文说明

2a. 代码审查

diff 干净且聚焦——每处改动都是从 SDK 类型到 CLI 参数 / initialize payload 的直接贯通。无正确性 bug，无安全问题，无过度抽象。

一个值得注意的缺口： PR 新增了验证逻辑（max_subagent_depth 范围检查、agents 必填字段检查），但没有为这些新代码路径添加测试。现有的 1163 TS / 58 Python 测试全部通过，但没有一个测试覆盖新选项。为验证和 CLI 参数生成添加测试会增强信心——尤其是验证有多个分支（bool 拒绝、范围边界、每个 agent 缺失字段）。

其余方面，实现很好地遵循了项目规范：

• TS：类型添加到 TransportOptions + QueryOptions，Zod schema 验证，通过 createQuery → ProcessTransport → buildCliArguments 传递。
• Python：定义了 TypedDict 类型，扩展了 QueryOptions dataclass，_as_optional_list_of_dicts 辅助函数遵循现有模式，验证镜像了 TS Zod 约束。

2b. 真实场景测试

SDK 测试套件（worktree，已应用 PR diff）：

TS SDK:   27 个测试文件，1163 个测试通过 ✓
Python SDK: 58 个测试通过 ✓

手动验证探测（Python SDK，tmux）：

$ PYTHONPATH=src python3 -c "..."
PASS: max_subagent_depth must be between 1 and 100   (拒绝 0)
PASS: max_subagent_depth must be between 1 and 100   (拒绝 101)
PASS: 5 accepted
PASS: agents[0] must have a non-empty 'description'  (拒绝不完整)
PASS: valid agent accepted

所有五个验证用例行为正确。

CLI 集成： 无法运行 npm run dev（CI 环境缺少 tsx）。通过代码检查确认 --max-subagent-depth 定义在 packages/cli/src/config/config.ts:903，带有整数验证和范围限制——SDK 正确传递了该参数。

TUI： 不适用——仅 SDK 变更，无用户可见输出。

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

This PR does exactly what it should: wire SDK types → validation → CLI args / initialize payload for sub-agent configuration. The implementation is minimal, follows project conventions, and every line in the diff serves the stated goal.

The one thing I'd ask the author to consider before merge: adding tests for the new validation branches (depth range, bool rejection, agent required fields) and CLI argument generation. The validation logic is correct — I verified it manually — but having it under test prevents regressions. Not blocking, but it would make this a stronger contribution.

Everything else checks out: existing test suites pass (1163 TS + 58 Python), types align with the CLI's actual --max-subagent-depth flag, and the Python SDK's agents initialize payload matches how the TS SDK already handles it.

Approving. ✅

中文说明

这个 PR 做了它该做的事：将 SDK 类型 → 验证 → CLI 参数 / initialize payload 贯通到子代理配置。实现最小化，遵循项目规范，diff 中的每一行都服务于声明的目标。

唯一想请作者在合并前考虑的：为新验证分支（深度范围、bool 拒绝、agent 必填字段）和 CLI 参数生成添加测试。验证逻辑是正确的——我手动验证过——但有测试覆盖可以防止回归。不是阻塞项，但会让贡献更完善。

其余一切正常：现有测试套件通过（1163 TS + 58 Python），类型与 CLI 实际的 --max-subagent-depth 参数对齐，Python SDK 的 agents initialize payload 与 TS SDK 的处理方式一致。

批准 ✅

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[qwen-code-ci-bot]

[Suggestion] SubagentConfig and RunConfig TypedDicts are defined here but never referenced — QueryOptions.agents is typed as list[dict[str, Any]] (lines 140 and 167), so these TypedDicts provide zero type-safety benefit. Callers get no IDE autocomplete or static checking.

Either wire them in:

agents: list[SubagentConfig] | None = None

Or remove them and keep list[dict[str, Any]], consistent with how mcp_servers is typed as dict[str, dict[str, Any]].

— qwen3.7-max via Qwen Code /review

[qwen-code-ci-bot]

[Suggestion] No tests added for the new code in this PR. _as_optional_list_of_dicts has 4 branches (None, not-list, non-mapping items, valid) with zero coverage. The validation blocks for max_subagent_depth (bool exclusion, range 1–100) and agents (required-field checks) in validation.py are also untested, as are the --max-subagent-depth CLI arg in transport.py and the agents payload in query.py.

Consider adding tests covering:

• _as_optional_list_of_dicts — valid list, non-list input, list with non-mapping items
• validate_query_options — max_subagent_depth boundaries (0, 1, 100, 101), bool rejection, agents missing required fields
• build_cli_arguments — --max-subagent-depth flag emission
• _initialize — agents included in control request payload when set

— qwen3.7-max via Qwen Code /review

[wenshao]

💡 Suggestion: Consolidate SDK PRs

Hi @juhuan, thanks for the comprehensive SDK work! We noticed you have 15 open PRs that all modify the same core files (transport.py, types.py, queryOptionsSchema.ts, types.ts, ProcessTransport.ts, createQuery.ts) and were created on the same day.

The problem

• Merge conflicts: Since all 15 PRs touch the same files, whichever merges first will cause conflicts in the remaining 14.
• Review overhead: Reviewing 15 near-identical PRs separately is inefficient and risks fatigue.
• CI cost: 15 separate CI runs for the same lint/typecheck passes.

Suggestion: regroup into 2 PRs

We recommend closing the current 15 PRs and reopening them as 2 consolidated PRs:

PR 1 — feat(sdk): expose transport and query options in both SDKs

Covers pure SDK-side option additions (~9 current PRs):

• disabled_slash_commands (feat(sdk): add disabled_slash_commands option to Python and TS SDKs #6480)
• sandbox, safe_mode, insecure, worktree CLI flags (feat(sdk): expose sandbox, safe_mode, insecure, worktree CLI flags #6479)
• fallback_model and proxy options (feat(sdk): add fallback_model and proxy options to Python and TS SDKs #6478)
• allowed_mcp_server_names (feat(sdk): add allowed_mcp_server_names option to both SDKs #6474)
• extensions option (feat(sdk): add extensions option to both SDKs #6470)
• extra_args option (feat(sdk): add extra_args option to both SDKs #6469)
• include_directories option (feat(sdk): add include_directories option to both SDKs #6468)
• sub-agent support / maxSubagentDepth (feat(sdk): add sub-agent support to Python SDK and maxSubagentDepth to both SDKs #6467)
• max_tool_calls option (feat(sdk): expose max_tool_calls option in Python and TypeScript SDKs #6461)
• mcp_servers support (feat(sdk-python): enable mcp_servers support via initialize control request #6463)
• fork_session option (feat(sdk): expose fork_session option in Python and TypeScript SDKs #6458)

PR 2 — feat(sdk): add control request methods to both SDKs

Covers features that also involve CLI-side ControlDispatcher changes (~4 current PRs):

• reasoning_effort option (feat(sdk): add reasoning effort option to CLI and both SDKs #6464)
• get_usage_info() control request (feat(sdk): add get_usage_info() control request to CLI and both SDKs #6473)
• get_context_usage() method (feat(sdk-python): add get_context_usage() method #6471)
• get_available_models() method (feat(sdk): add get_available_models() to Python and TypeScript SDKs #6460)

This keeps a reasonable separation of concerns while eliminating the merge-conflict chain and making review much more manageable.

/cc @juhuan

[wenshao]

Closing in favor of consolidated PRs (see suggestion comment above). Please reopen as 2 grouped PRs.