feat(sdk-python): add get_context_usage() method

[juhuan]

Summary

Add get_context_usage(show_details=False) method to the Python SDK's Query class, which sends the get_context_usage control request to the CLI. Also adds the CLIControlGetContextUsageRequest protocol type.

The TS SDK already has getContextUsage(), and the CLI already handles the get_context_usage control request in SystemController.

Test plan

• Python SDK tests pass (pytest — 58 passed)

[qwen-code-ci-bot]

Hey @juhuan — thanks for the contribution! The code change itself looks clean, but the PR body doesn't follow our PR template. Could you update the description to include the required sections?

Specifically, the template asks for:

• What this PR does (currently ## Summary)
• Why it's needed (motivation / problem being solved)
• Reviewer Test Plan with subsections: How to verify, Evidence (Before & After), Tested on
• Risk & Scope
• Linked Issues
• A <details>中文说明</details> block with a Chinese translation

This helps reviewers (and future-you) understand the context quickly. Happy to re-run triage once it's updated. 🙏

中文说明

嗨 @juhuan — 感谢贡献！代码改动本身看起来没问题，但 PR 描述没有按照我们的 PR 模板 填写。能否更新一下描述，补上必要的章节？

具体来说，模板要求包含：

• What this PR does（目前是 ## Summary）
• Why it's needed（动机 / 要解决的问题）
• Reviewer Test Plan 及子章节：验证方法、Evidence（Before & After）、Tested on
• Risk & Scope
• Linked Issues
• 一个 <details>中文说明</details> 块，包含中文翻译

这些信息能帮助 reviewer 更快理解上下文。更新后可以重新跑 triage。🙏

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

[Suggestion] The async Query class now has get_context_usage(), but SyncQuery in sync_query.py is missing the corresponding sync wrapper. Every other control-request method (supported_commands, mcp_server_status, set_model, set_permission_mode) has a sync counterpart. Sync SDK consumers currently have no way to call this new feature.

Consider adding to SyncQuery (after mcp_server_status):

def get_context_usage(self, show_details: bool = False) -> Any:
    q = self._require_query()
    return asyncio.run_coroutine_threadsafe(
        q.get_context_usage(show_details),
        self._loop,
    ).result(timeout=q.control_request_timeout + _SYNC_TIMEOUT_MARGIN)

— qwen3.7-max via Qwen Code /review

[qwen-code-ci-bot]

[Suggestion] No tests were added for get_context_usage(). The TS SDK has dedicated unit tests (Query.test.ts lines 1211-1287) covering the request payload, show_details parameter forwarding, response deserialization, and closed-query error handling. The Python SDK has analogous tests for supported_commands() and mcp_server_status() in test_query_core.py and integration tests.

Additionally, the integration test mock in tests/integration/conftest.py has no handler for the get_context_usage subtype — it falls through to the error branch, so integration tests cannot exercise this path.

Suggested additions:

• Unit test in test_query_core.py verifying the outgoing payload contains {"subtype": "get_context_usage", "show_details": True/False} and that a mock response is returned correctly
• A get_context_usage branch in conftest.py's mock CLI handler returning a representative response
• Optionally, an integration test in test_async_query.py

— 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.