docs(reference): document run_subagent's provider, three gateway groups, and max_tokens (#126)

Co-authored-by: Cursor <cursoragent@cursor.com>

changelog/unreleased/2026-07-30-docs-tools-and-configuration-reference.md

@@ -0,0 +1,9 @@
+# Docs: the Tools and Configuration references match the code again
+
+Three reference blocks had fallen behind the codes they document
+
+`run_subagent`'s argument block listed `model_id` alone, though a model is always referenced by the complete `(provider, model_id)` pair: the tool schema declares both and rejects a call carrying only one, and the page's own prose already said as much. Only the code block was stale, and it is the part a reader copies — both language editions now list `provider` beside `model_id`.
+
+The provider credential table covered nine of the twelve groups in `MODEL_PROVIDERS`, omitting the `fireworks`, `qwen-token-plan` and `qwen-pay-as-you-go` gateways. All three read `OPENAI_API_KEY` / `OPENAI_BASE_URL`, for the same reason `openrouter` and `siliconflow` were already on that row: a gateway's model ids cannot be auto-routed, so its entries go through the OpenAI client. For a group missing from the table the natural guess is wrong twice over, since neither a vendor-shaped `FIREWORKS_API_KEY` nor the variable of the vendor whose model the gateway resells is ever read.
+
+The Project model entry table skipped `max_tokens`, the per-model output cap that overrides the Agent's `model.max_tokens` when set. It is what makes a narrow-context model usable at all — the seeded Agent default of 32000 cannot fit a small window alongside any prompt, and the upstream rejects such a request outright — and the CLI reference already documented the flag that writes it.

changelog/unreleased/README.md

@@ -2,6 +2,8 @@
 
 Changes since v0.1.4. The version number is assigned at release, when this folder is renamed.
 
+- [2026-07-30] Docs: three reference blocks catch up with the code they document — `run_subagent`'s argument block lists the `provider` that `model_id` must be paired with, the provider credential table covers the three gateway groups it had been missing, and the Project model entry table documents `max_tokens`. ([details](2026-07-30-docs-tools-and-configuration-reference.md))
+
 - [2026-07-29] Core: every LLM failure except a rejected credential now retries inside the run — the classifier separating transient from permanent is an allowlist, so a gateway wording a transient fault its own way used to kill the turn — with the retry visible in both frontends, compaction on the same set under its own shorter budget, and a recovered failure no longer reported to the operator as an incident. Separately, pressing Stop mid-request can no longer leave a Session running forever when the provider's stream neither yields nor rejects after the abort. ([details](2026-07-29-llm-request-lifecycle.md))
 
 - [2026-07-29] Cost center: the error table can page back through the whole history instead of showing only the newest 20, its source column reads `[env]` rather than `environment ·`, and an ordinary non-zero exit from a command tool is no longer recorded as an error — `grep` finding nothing had been crowding out the failures the table exists to show. ([details](2026-07-29-cost-center-errors.md))

packages/docs/content/configuration.en.md

@@ -32,12 +32,12 @@ When a model entry has no inline `api_key`, the AgentHub gateway falls back to t
 | --- | --- | --- |
 | deepseek | `DEEPSEEK_API_KEY` | `DEEPSEEK_BASE_URL` |
 | anthropic | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` |
-| openai, openrouter, siliconflow, custom | `OPENAI_API_KEY` | `OPENAI_BASE_URL` |
+| openai, openrouter, fireworks, siliconflow, qwen-token-plan, qwen-pay-as-you-go, custom | `OPENAI_API_KEY` | `OPENAI_BASE_URL` |
 | google | `GEMINI_API_KEY` | `GEMINI_BASE_URL` |
 | zhipu | `ZAI_API_KEY` | `ZAI_BASE_URL` |
 | moonshot | `MOONSHOT_API_KEY` | `MOONSHOT_BASE_URL` |
 
-The openrouter, siliconflow, and custom groups speak the OpenAI-compatible protocol, hence the shared `OPENAI_*` variables. Provider groups and the built-in model catalog are covered in [Models & Providers](/models).
+The openrouter, fireworks, siliconflow, qwen-token-plan, qwen-pay-as-you-go, and custom groups speak the OpenAI-compatible protocol, hence the shared `OPENAI_*` variables. Provider groups and the built-in model catalog are covered in [Models & Providers](/models).
 
 ## Project config
 
@@ -60,6 +60,7 @@ Model entry (`[[models]]`) fields:
 | `client_type` | AgentHub client protocol; inferred from `model_id` by default — third-party OpenAI-compatible models should set `openai` |
 | `display_name` | Display name; persisted only when it differs from the built-in catalog |
 | `vision` | Whether image input is supported; defaults to supported |
+| `max_tokens` | Per-model max output tokens; overrides the Agent's `model.max_tokens` when set, omitted = inherit it |
 | `pricing` | Three price buckets `cache_read` / `cache_write` / `output`, in USD per million Tokens (`unit = "usd_per_mtok"`) |
 | `api_key` | Inline credential; when empty, falls back to the provider environment variable |
 | `base_url` | Custom base URL; preset for gateway models |

packages/docs/content/configuration.zh.md

@@ -32,12 +32,12 @@ CLI 与服务端启动时会自动加载工作目录下的 `.env` 文件。
 | --- | --- | --- |
 | deepseek | `DEEPSEEK_API_KEY` | `DEEPSEEK_BASE_URL` |
 | anthropic | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` |
-| openai、openrouter、siliconflow、custom | `OPENAI_API_KEY` | `OPENAI_BASE_URL` |
+| openai、openrouter、fireworks、siliconflow、qwen-token-plan、qwen-pay-as-you-go、custom | `OPENAI_API_KEY` | `OPENAI_BASE_URL` |
 | google | `GEMINI_API_KEY` | `GEMINI_BASE_URL` |
 | zhipu | `ZAI_API_KEY` | `ZAI_BASE_URL` |
 | moonshot | `MOONSHOT_API_KEY` | `MOONSHOT_BASE_URL` |
 
-openrouter、siliconflow 与 custom 分组走 OpenAI 兼容协议，因此复用 `OPENAI_*` 变量。Provider 分组与内置模型目录见[模型与 Provider](/models)。
+openrouter、fireworks、siliconflow、qwen-token-plan、qwen-pay-as-you-go 与 custom 分组走 OpenAI 兼容协议，因此复用 `OPENAI_*` 变量。Provider 分组与内置模型目录见[模型与 Provider](/models)。
 
 ## Project 配置
 
@@ -60,6 +60,7 @@ openrouter、siliconflow 与 custom 分组走 OpenAI 兼容协议，因此复用
 | `client_type` | AgentHub 客户端协议；缺省由 `model_id` 推断，OpenAI 兼容的第三方模型应设为 `openai` |
 | `display_name` | 展示名；仅在与内置目录不同时持久化 |
 | `vision` | 是否支持图片输入；缺省视为支持 |
+| `max_tokens` | 单模型最大输出 Token；设置后覆盖 Agent 的 `model.max_tokens`，缺省则继承 |
 | `pricing` | 三档价格 `cache_read` / `cache_write` / `output`，单位 USD 每百万 Token（`unit = "usd_per_mtok"`） |
 | `api_key` | 内联凭证；留空回退到 Provider 环境变量 |
 | `base_url` | 自定义 Base URL；网关模型预置 |

packages/docs/content/tools.en.md

@@ -160,7 +160,8 @@ On POSIX, Ctrl-C sends `SIGINT` to the session's process group, interrupting the
 {
   prompt: string;          // required: the complete subtask (all context + the exact final output expected)
   agent_id?: string;       // the child Agent; defaults to the current Agent
-  model_id?: string;       // the child Session's model; inherits the parent Session's model when omitted
+  model_id?: string;       // the child Session's model, paired with provider; omit both to inherit the parent Session's model
+  provider?: string;       // the provider group model_id belongs to; required whenever model_id is given
   yield_time_ms?: number;  // foreground wait; default 300000
   description: string;     // required while call_description is on
 }

packages/docs/content/tools.zh.md

@@ -158,7 +158,8 @@ POSIX 上 Ctrl-C 向会话进程组发送 `SIGINT`，中断前台命令。Window
 {
   prompt: string;          // 必填:完整的子任务(含全部上下文与期望的最终产出)
   agent_id?: string;       // 子 Agent;缺省复用当前 Agent
-  model_id?: string;       // 子 Session 模型;缺省继承父 Session 的模型
+  model_id?: string;       // 子 Session 模型,须与 provider 成对给出;两者都缺省时继承父 Session 的模型
+  provider?: string;       // model_id 所属的 provider 组;给出 model_id 时必填
   yield_time_ms?: number;  // 前台等待时长;默认 300000
   description: string;     // 开关开启时必填
 }