docs: document delegateTask/task_run model override behavior

Author: Gui-Yue

docs/en/advanced/multi-agent.md

@@ -76,8 +76,8 @@ class AgentPool {
     strategy?: 'crash' | 'manual';
   }): Promise<Agent>;
 
-  // Destroy an agent
-  async destroy(agentId: string): Promise<void>;
+  // Delete an agent
+  async delete(agentId: string): Promise<void>;
 }
 ```
 
@@ -190,7 +190,7 @@ deps.toolRegistry.register('task_run', () => taskRunTool);
 
 When an Agent calls `task_run`:
 
-1. Agent specifies `agentTemplateId`, `prompt`, and optional `context`
+1. Agent specifies `agentTemplateId`, `prompt`, optional `context`, and optional `model`
 2. SDK creates a sub-Agent with the specified template
 3. Sub-Agent processes the task
 4. Result returns to parent Agent
@@ -203,6 +203,7 @@ interface TaskRunParams {
   prompt: string;           // Detailed instructions
   agentTemplateId: string;  // Template ID to use
   context?: string;         // Additional context
+  model?: string | { provider: string; model: string }; // Optional model override
 }
 ```
 
@@ -217,6 +218,14 @@ interface TaskRunResult {
 }
 ```
 
+**Model Inheritance Notes (`delegateTask`):**
+- `task_run` accepts an optional `model` argument; when omitted, delegated sub-Agents reuse the parent Agent's `ModelProvider` instance.
+- If you need explicit model control, call `agent.delegateTask(...)` directly:
+  - omit `model`: inherit parent model instance
+  - `model: string`: keep parent provider type, override model ID (custom providers require `modelFactory`)
+  - `model: { provider, model }`: explicitly choose provider + model (custom providers usually require `modelFactory` when provider differs)
+  - `model: ModelProvider`: use provided provider instance directly
+
 ### Sub-Agent Configuration
 
 Configure sub-agent behavior in template:

docs/en/guides/providers.md

@@ -247,7 +247,6 @@ const provider = new GeminiProvider(
   {
     thinking: {
       level: 'medium',  // 'minimal' | 'low' | 'medium' | 'high'
-      includeThoughts: true,
     },
   }
 );

docs/en/guides/thinking.md

@@ -101,7 +101,6 @@ const provider = new GeminiProvider(
   {
     thinking: {
       level: 'medium',  // 'minimal' | 'low' | 'medium' | 'high'
-      includeThoughts: true,
     },
     reasoningTransport: 'text',
   }

docs/en/guides/tools.md

@@ -60,8 +60,65 @@ const agent = await Agent.create({
 
 ### Task (Sub-Agent)
 
-- `task_run`: Dispatch sub-Agents from template pool, supports `subagent_type`, `context`, `model_name` parameters
-- Templates can limit depth and available templates via `runtime.subagents`
+- `task_run`: Delegate complex work to a sub-Agent selected from your template pool.
+- Parameters:
+  - `description`: Short task title (recommended 3-5 words)
+  - `prompt`: Detailed instructions for the sub-Agent
+  - `agentTemplateId`: Must match a registered template ID
+  - `context`: Optional extra background (appended to the prompt)
+  - `model`: Optional model override
+    - `string`: keep parent provider, override model ID
+    - `{ provider, model }`: explicitly choose provider + model
+- Return fields:
+  - `status`: `ok` or `paused`
+  - `template`: Template ID that was used
+  - `text`: Sub-Agent output
+  - `permissionIds`: Pending permission IDs (if any)
+- Templates can restrict delegation depth and allowed template IDs via `runtime.subagents`.
+
+**Minimal Example:**
+
+```typescript
+import { createTaskRunTool } from '@shareai-lab/kode-sdk';
+
+const templates = [
+  { id: 'researcher', system: 'Research and return structured findings.', whenToUse: 'Need search + analysis' },
+  { id: 'writer', system: 'Turn findings into publishable copy.', whenToUse: 'Need final draft' },
+];
+
+const taskRunTool = createTaskRunTool(templates);
+deps.toolRegistry.register('task_run', () => taskRunTool);
+
+// Example tool-call args:
+// {
+//   "description": "Research pricing",
+//   "prompt": "Analyze 3 competitors and provide a price table plus recommended range.",
+//   "agentTemplateId": "researcher",
+//   "context": "Target market: North America SMB",
+//   "model": { "provider": "openai", "model": "gpt-4.1-mini" }
+// }
+```
+
+**Common Errors:**
+- `Agent template 'xxx' not found`: `agentTemplateId` is not in the `createTaskRunTool(templates)` list.
+- Delegation stops unexpectedly: check `runtime.subagents` limits (depth/allowed templates).
+
+**delegateTask Model Behavior (Important):**
+- In `task_run`, `model` is optional. If omitted, sub-Agent reuses parent Agent's `ModelProvider` instance by default.
+- If you call `agent.delegateTask(...)` directly, model resolution is:
+  - `model` omitted: reuse parent `ModelProvider` instance (no `modelFactory` required)
+  - `model` is `string`: keep parent provider type and only override model ID (for custom providers, this path requires `modelFactory`)
+  - `model` is `{ provider, model }`: explicitly choose provider + model (if provider differs from parent, custom providers usually require `modelFactory`)
+  - `model` is `ModelProvider`: use that instance directly
+
+```typescript
+// Direct call with explicit model override
+await agent.delegateTask({
+  templateId: 'researcher',
+  prompt: 'Analyze competitors and produce a pricing matrix.',
+  model: 'gpt-4.1', // same provider type as parent, model id overridden
+});
+```
 
 ### Skills Tool
 

docs/en/reference/api.md

@@ -130,6 +130,25 @@ Creates a forked Agent from a snapshot.
 async fork(sel?: SnapshotId | { at?: string }): Promise<Agent>
 ```
 
+#### `agent.delegateTask(config)`
+
+Create and run a delegated sub-Agent task (commonly used by `task_run`).
+
+```typescript
+async delegateTask(config: {
+  templateId: string;
+  prompt: string;
+  model?: string | { provider: string; model: string } | ModelProvider;
+  tools?: string[];
+}): Promise<CompleteResult>
+```
+
+**Model resolution rules:**
+- `model` omitted: reuse parent `ModelProvider` instance.
+- `model` is `string`: keep parent provider type and override only model ID (for custom providers, this path requires `modelFactory`).
+- `model` is `{ provider, model }`: explicitly choose provider + model (for custom providers, this path usually requires `modelFactory` when provider differs).
+- `model` is `ModelProvider`: use the provided instance directly.
+
 #### `agent.status()`
 
 Returns current Agent status.
@@ -237,6 +256,8 @@ interface AgentConfig {
   tools?: string[];                    // Tool names to enable
   exposeThinking?: boolean;            // Emit thinking events
   retainThinking?: boolean;            // Keep thinking in message history
+  multimodalContinuation?: 'history';  // Preserve multimodal context across turns
+  multimodalRetention?: { keepRecent?: number };  // Keep recent multimodal items
   overrides?: {
     permission?: PermissionConfig;
     todo?: TodoConfig;
@@ -482,7 +503,7 @@ class AgentTemplateRegistry {
   bulkRegister(templates: AgentTemplateDefinition[]): void;
   has(id: string): boolean;
   get(id: string): AgentTemplateDefinition;
-  list(): string[];
+  list(): AgentTemplateDefinition[];
 }
 ```
 
@@ -521,7 +542,7 @@ class AgentPool {
   async status(agentId: string): Promise<AgentStatus | undefined>;
   async fork(agentId: string, snapshotSel?: SnapshotId | { at?: string }): Promise<Agent>;
   async resume(agentId: string, config: AgentConfig, opts?: { autoRun?: boolean; strategy?: ResumeStrategy }): Promise<Agent>;
-  async destroy(agentId: string): Promise<void>;
+  async delete(agentId: string): Promise<void>;
 }
 ```
 
@@ -573,9 +594,10 @@ import { AnthropicProvider } from '@shareai-lab/kode-sdk';
 const provider = new AnthropicProvider(
   process.env.ANTHROPIC_API_KEY!,
   process.env.ANTHROPIC_MODEL_ID ?? 'claude-sonnet-4-20250514',
+  process.env.ANTHROPIC_BASE_URL, // optional
+  process.env.HTTPS_PROXY, // optional
   {
     thinking: { enabled: true, budgetTokens: 10000 },
-    cache: { breakpoints: 4 },
   }
 );
 ```
@@ -588,6 +610,8 @@ import { OpenAIProvider } from '@shareai-lab/kode-sdk';
 const provider = new OpenAIProvider(
   process.env.OPENAI_API_KEY!,
   process.env.OPENAI_MODEL_ID ?? 'gpt-4o',
+  process.env.OPENAI_BASE_URL, // optional
+  process.env.HTTPS_PROXY, // optional
   {
     api: 'responses',
     responses: { reasoning: { effort: 'medium' } },
@@ -603,8 +627,10 @@ import { GeminiProvider } from '@shareai-lab/kode-sdk';
 const provider = new GeminiProvider(
   process.env.GOOGLE_API_KEY!,
   process.env.GEMINI_MODEL_ID ?? 'gemini-2.0-flash',
+  process.env.GEMINI_BASE_URL, // optional
+  process.env.HTTPS_PROXY, // optional
   {
-    thinking: { level: 'medium', includeThoughts: true },
+    thinking: { level: 'medium' },
   }
 );
 ```

docs/zh-CN/advanced/multi-agent.md

@@ -76,8 +76,8 @@ class AgentPool {
     strategy?: 'crash' | 'manual';
   }): Promise<Agent>;
 
-  // 销毁 agent
-  async destroy(agentId: string): Promise<void>;
+  // 删除 agent
+  async delete(agentId: string): Promise<void>;
 }
 ```
 
@@ -190,7 +190,7 @@ deps.toolRegistry.register('task_run', () => taskRunTool);
 
 当 Agent 调用 `task_run` 时：
 
-1. Agent 指定 `agentTemplateId`、`prompt` 和可选的 `context`
+1. Agent 指定 `agentTemplateId`、`prompt`、可选 `context` 与可选 `model`
 2. SDK 使用指定模板创建子 Agent
 3. 子 Agent 处理任务
 4. 结果返回给父 Agent
@@ -203,6 +203,7 @@ interface TaskRunParams {
   prompt: string;           // 详细指令
   agentTemplateId: string;  // 使用的模板 ID
   context?: string;         // 额外上下文
+  model?: string | { provider: string; model: string }; // 可选模型覆盖
 }
 ```
 
@@ -217,6 +218,14 @@ interface TaskRunResult {
 }
 ```
 
+**模型继承说明（`delegateTask`）：**
+- `task_run` 支持可选 `model` 参数；不传时，默认让被委派的子 Agent 复用父 Agent 的 `ModelProvider` 实例。
+- 如果你需要显式控制模型，请直接调用 `agent.delegateTask(...)`：
+  - 不传 `model`：继承父模型实例
+  - `model: string`：保持父 provider 类型，仅覆盖模型 ID（自定义 provider 需配合 `modelFactory`）
+  - `model: { provider, model }`：显式指定 provider + model（provider 与父模型不同时，自定义 provider 通常需配合 `modelFactory`）
+  - `model: ModelProvider`：直接使用传入的 provider 实例
+
 ### 子 Agent 配置
 
 在模板中配置子 agent 行为：

docs/zh-CN/guides/providers.md

@@ -247,7 +247,6 @@ const provider = new GeminiProvider(
   {
     thinking: {
       level: 'medium',  // 'minimal' | 'low' | 'medium' | 'high'
-      includeThoughts: true,
     },
   }
 );

docs/zh-CN/guides/thinking.md

@@ -101,7 +101,6 @@ const provider = new GeminiProvider(
   {
     thinking: {
       level: 'medium',  // 'minimal' | 'low' | 'medium' | 'high'
-      includeThoughts: true,
     },
     reasoningTransport: 'text',
   }

docs/zh-CN/guides/tools.md

@@ -60,8 +60,65 @@ const agent = await Agent.create({
 
 ### Task（子代理）
 
-- `task_run`：根据模板池派发子 Agent，支持 `subagent_type`、`context`、`model_name` 参数
-- 模板可以通过 `runtime.subagents` 限制深度与可选模板
+- `task_run`：把复杂任务委派给指定模板的子 Agent。
+- 参数说明：
+  - `description`：任务短标题（建议 3-5 词）
+  - `prompt`：对子 Agent 的详细执行指令
+  - `agentTemplateId`：必须是模板池中已注册的模板 ID
+  - `context`：可选，附加背景信息（会拼接到 prompt 后）
+  - `model`：可选的模型覆盖参数
+    - `string`：沿用父 provider，仅覆盖 model ID
+    - `{ provider, model }`：显式指定 provider + model
+- 返回结果：
+  - `status`：`ok` 或 `paused`
+  - `template`：实际使用的模板 ID
+  - `text`：子 Agent 输出
+  - `permissionIds`：待审批权限 ID 列表（如有）
+- 模板可以通过 `runtime.subagents` 限制递归深度和可选模板。
+
+**最小示例：**
+
+```typescript
+import { createTaskRunTool } from '@shareai-lab/kode-sdk';
+
+const templates = [
+  { id: 'researcher', system: '你负责调研并给出结构化结论。', whenToUse: '需要先检索再总结' },
+  { id: 'writer', system: '你负责把结果整理成可发布文稿。', whenToUse: '需要生成最终文稿' },
+];
+
+const taskRunTool = createTaskRunTool(templates);
+deps.toolRegistry.register('task_run', () => taskRunTool);
+
+// Agent 在工具调用时传参示例：
+// {
+//   "description": "调研竞品定价",
+//   "prompt": "调研 3 个主要竞品，输出价格对比表和建议定价区间。",
+//   "agentTemplateId": "researcher",
+//   "context": "目标市场：北美中小企业",
+//   "model": { "provider": "openai", "model": "gpt-4.1-mini" }
+// }
+```
+
+**常见问题：**
+- `Agent template 'xxx' not found`：`agentTemplateId` 不在传入 `createTaskRunTool(templates)` 的列表中。
+- 无法继续委派：检查模板的 `runtime.subagents` 配置是否限制了可用模板或深度。
+
+**delegateTask 的模型行为（重要）：**
+- `task_run` 中 `model` 是可选参数；不传时，子 Agent 默认复用父 Agent 的 `ModelProvider` 实例。
+- 如果你直接调用 `agent.delegateTask(...)`，模型解析规则为：
+  - 不传 `model`：复用父 `ModelProvider` 实例（不依赖 `modelFactory`）
+  - `model` 为 `string`：沿用父 provider 类型，仅覆盖 model ID（自定义 provider 走这条时需要 `modelFactory`）
+  - `model` 为 `{ provider, model }`：显式指定 provider + model（provider 与父模型不同时，自定义 provider 通常需要 `modelFactory`）
+  - `model` 为 `ModelProvider`：直接使用该实例
+
+```typescript
+// 直接调用并覆盖 model
+await agent.delegateTask({
+  templateId: 'researcher',
+  prompt: '分析竞品并输出定价矩阵。',
+  model: 'gpt-4.1', // 继承父 provider 类型，只覆盖模型 ID
+});
+```
 
 ### Skills 工具