@ai-agent-forge/plugin-subagent-delegate 0.88.14 → 0.88.16

package/MANUAL.md

@@ -1,23 +1,19 @@
-# subagent-delegate 能力手册(AI 用)
-
-多代理编排:把可并行的独立子任务委派给子代理会话执行,主会话保持轻量。子代理有自己的上下文、工具面与模型,结果回传主会话。
-
-## 工具速查
-
-| 工具 | 用途 |
-| --- | --- |
-| subagent_run | 委派新子代理任务(单次最多 4 个并发) |
-| subagent_list | 列出本会话的子代理与状态 |
-| subagent_result | 读取(等待)子代理结果 |
-| subagent_send / subagent_inbox | 向子代理发消息 / 收信箱 |
-| subagent_steer | 运行中转向(补充指令) |
-| subagent_cancel / subagent_resume | 取消 / 恢复 |
-| subagent_escalate | 子代理向主会话升级问题 |
-| subagent_role_set / role_list / role_remove | 角色(系统提示+工具档案)管理 |
-
-## 使用原则
-
-1. **只委派可独立完成的任务**:明确输入/输出/验收;需要共享实时状态或频繁往返的活自己干。
-2. **角色隔离**:用 `role_set` 定义的角色按"术有专攻"分工(explore/reviewer/design-proposer 等),不要把编码任务给审查角色。
-3. **结果有界**:子代理回报是摘要与结论,不是全量文件内容;需要细节让子代理写文件、主会话按路径读。
-4. 并发上限与队列深度、超时由插件 config 管控(默认 8 并发/任务 5 分钟超时),超限调用会得到结构化错误。
+# subagent-delegate 能力手册(AI 用)
+
+多代理编排:把可并行的独立子任务委派给子代理会话执行,主会话保持轻量。子代理有自己的上下文、工具面与模型,结果回传主会话。
+
+## 工具速查
+
+| 工具 | 用途 |
+| --- | --- |
+| subagent_run | 委派新子代理任务(单次最多 8 个并发) |
+| subagent_task | `type`: result 读取(等待)结果 / list 列出本会话子代理 / cancel 取消 / steer 运行中转向 / resume 继续已终态会话 |
+| subagent_message | 子代理侧通信: send 给兄弟发消息 / inbox 收信箱 / escalate 向父会话升级问题 |
+| subagent_role | 角色(系统提示+工具档案)管理: set 注册或更新 / list 查看 / remove 删除 |
+
+## 使用原则
+
+1. **只委派可独立完成的任务**:明确输入/输出/验收;需要共享实时状态或频繁往返的活自己干。
+2. **角色隔离**:用 `subagent_role`(type `set`)定义的角色按"术有专攻"分工(explore/reviewer/design-proposer 等),不要把编码任务给审查角色。
+3. **结果有界**:子代理回报是摘要与结论,不是全量文件内容;需要细节让子代理写文件、主会话按路径读。
+4. 并发上限与队列深度、超时由插件 config 管控(默认 12 并发/任务 10 分钟超时),超限调用会得到结构化错误。

package/README.md

@@ -1,54 +1,59 @@
-# @agent-forge/plugin-subagent-delegate
-
-First-party subagent-delegate capability plugin for Agent Forge: the
-`subagent_run` / `subagent_result` (and optionally `subagent_resume` /
-`subagent_list` / communication tools) model face over the plugin-level
-`SubagentRuntime` scheduler, extracted from the host's embedded builtin
-capability (D-075 S4, third batch).
-
-## Library face vs plugin entry
-
-- `createSubagentDelegateCapability(api, options?)` — explicit-options
-  factory for embedders and tests. Adapter/limits/runner spawner/roles are
-  injected explicitly.
-- `./dist/entry.js` (default export) — the manifest-loaded plugin factory. It
-  maps host services onto the same options:
-  - `api.host.communication` → `communicationWiring`
-  - `api.host.turnContext.backgroundDigestSink` / `getTurnCorrelationId`
-  - `api.host.agentDir` + `api.host.roleAssociations` → role catalog (after an
-    idempotent factory seed of `<agentDir>/roles/`: `explore`, `reviewer`,
-    `design-proposer`, `visual-reviewer` — the latter two are the visual
-    baseline roles (2026-10-04, "术有专攻"): read-only profile narrowed to
-    `["read"]`, instructions embed the aesthetic baseline assets; see
-    `docs/plans/视觉保底角色设计注记.md`)
-  - `api.host.agentDir` → the nested-depth lineage gate source
-  - auto-pooling is driven by the existing config key `runnerEntryAuto`
-- Config channel: hosts declaring `api.host.agentDir` get
-  `<agentDir>/capabilities/builtin.subagent-delegate.json` merged over the
-  manifest config (missing file = unconfigured; unreadable/invalid JSON fails
-  the plugin load).
-
-## Bundled modules
-
-The scheduler (`subagent-runtime`), multi-agent task registry
-(`multi-agent-tasks`), runner pool / spawner, remote (wire) and shared
-(in-process) adapters, and the self-invocation probe all live in this package
-and are re-exported from the index. The wire protocol, stdio channel, task
-server, progress face, and mailbox come from `@agent-forge/protocol`;
-agent-task contracts, durable service types, and session lineage reading come
-from `@agent-forge/plugin-sdk`.
-
-## 关闭边界与真实验收
-
-runner pool 关闭后不再接受任务。在途 hello 被取消，尚未完成的 spawn 返回句柄后直接回收，
-不登记 runner 或再发 create，不触发替代 spawn；已经完成的任务结果保持原样。
-spawn 工厂同步失败保留原错并结束本次创建，下一次显式创建可恢复，不会自动重跑原任务。
-真实 pooled 验收先在测试私有 agentDir 通过生产 bootstrap 准备插件依赖，再计时验证模型任务、
-取消和崩溃恢复。准备成功必须有实际 bootstrap 结果，offline/disabled 跳过不算成功。
-详见 `docs/design/冷资源准备与取消边界.md`。
-
-## Capabilities
-
-Requires `session` + `tools`; `agents` is optional (leaf sessions register
-their child communication face only). Provides the
-`subagent-delegate.agent-task` service (v1).
+# @agent-forge/plugin-subagent-delegate
+
+First-party subagent-delegate capability plugin for Agent Forge: the
+four-tool model face (`subagent_run`, `subagent_task`, `subagent_message`,
+`subagent_role`; each merged tool takes a `type` discriminator) over the
+plugin-level `SubagentRuntime` scheduler, extracted from the host's embedded
+builtin capability (D-075 S4, third batch).
+
+## Library face vs plugin entry
+
+- `createSubagentDelegateCapability(api, options?)` — explicit-options
+  factory for embedders and tests. Adapter/limits/runner spawner/roles are
+  injected explicitly.
+- `./dist/entry.js` (default export) — the manifest-loaded plugin factory. It
+  maps host services onto the same options:
+  - `api.host.communication` → `communicationWiring`
+  - `api.host.turnContext.backgroundDigestSink` / `getTurnCorrelationId`
+  - `api.host.agentDir` + `api.host.roleAssociations` → role catalog (after an
+    idempotent factory seed of `<agentDir>/roles/`: `explore`, `reviewer`,
+    `design-proposer`, `visual-reviewer` — the latter two are the visual roles
+    (2026-10-04, "术有专攻"): read-only profile narrowed to `["read"]`,
+    instructions use a shared work definition and six project-derived methods
+    inspired by Chinese aesthetic thought, selected according to intent and
+    context rather than a fixed style. The reviewer checks actual observable
+    visual presentation, reports only what the evidence supports, and uses
+    `fail`, `Unverified` or `pass` according to known violations and required
+    evidence; see
+    `docs/plans/视觉保底角色设计注记.md`)
+  - `api.host.agentDir` → the nested-depth lineage gate source
+  - auto-pooling is driven by the existing config key `runnerEntryAuto`
+- Config channel: hosts declaring `api.host.agentDir` get
+  `<agentDir>/capabilities/builtin.subagent-delegate.json` merged over the
+  manifest config (missing file = unconfigured; unreadable/invalid JSON fails
+  the plugin load).
+
+## Bundled modules
+
+The scheduler (`subagent-runtime`), multi-agent task registry
+(`multi-agent-tasks`), runner pool / spawner, remote (wire) and shared
+(in-process) adapters, and the self-invocation probe all live in this package
+and are re-exported from the index. The wire protocol, stdio channel, task
+server, progress face, and mailbox come from `@agent-forge/protocol`;
+agent-task contracts, durable service types, and session lineage reading come
+from `@agent-forge/plugin-sdk`.
+
+## 关闭边界与真实验收
+
+runner pool 关闭后不再接受任务。在途 hello 被取消，尚未完成的 spawn 返回句柄后直接回收，
+不登记 runner 或再发 create，不触发替代 spawn；已经完成的任务结果保持原样。
+spawn 工厂同步失败保留原错并结束本次创建，下一次显式创建可恢复，不会自动重跑原任务。
+真实 pooled 验收先在测试私有 agentDir 通过生产 bootstrap 准备插件依赖，再计时验证模型任务、
+取消和崩溃恢复。准备成功必须有实际 bootstrap 结果，offline/disabled 跳过不算成功。
+详见 `docs/design/冷资源准备与取消边界.md`。
+
+## Capabilities
+
+Requires `session` + `tools`; `agents` is optional (leaf sessions register
+their child communication face only). Provides the
+`agent-forge.agent-task-scheduler` service (v1).

package/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.subagent-delegate",
-	"pluginVersion": "0.88.14",
+	"pluginVersion": "0.88.16",
 	"apiVersion": "1",
 	"minHostVersion": "0.84.4",
 	"platform": {

package/dist/defaults.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 子代理调度器出厂默认值（docs/design/产品默认值清单.md）。
+ * 单一定义源：capability manifest（delegate.ts）、runner 装配（subagent-runtime.ts）
+ * 与 plugin.json 的 config 声明共用；用户经
+ * `<agentDir>/capabilities/builtin.subagent-delegate.json` 覆盖。
+ *
+ * 2026-10-19 重度并行画像调定：maxConcurrentSubagents 是**每会话**上限（调度器
+ * 实例每主会话一个，进程内无全局子代理闸门）；12 = 单会话 1.5×8，20 会话理论峰值
+ * 240 个并发子代理（G2 实测进程内簿记约 1.1MB/个，200 并发 ≈220MB），实际瓶颈是
+ * provider 限流。大小预算（bytes/maxMessages）不是并发，未调。
+ */
+export declare const DEFAULT_SUBAGENT_LIMITS: {
+    readonly maxConcurrentSubagents: 12;
+    readonly maxQueueDepth: 200;
+    readonly maxPromptBytes: 65536;
+    readonly maxMetadataBytes: 16384;
+    readonly maxResultBytes: 524288;
+    readonly maxMessages: 2000;
+    readonly drainTimeoutMs: 30000;
+    readonly maxRetainedRecords: 512;
+};
+/** 单次 `subagent_run` 并行扇出（与 12 并发对齐，避免小任务组被硬拒绝）。 */
+export declare const DEFAULT_SUBAGENT_MAX_TASKS_PER_CALL = 8;
+/** 前台阻塞 drain 预算（10 分钟，减少长编码任务被 5 分钟超时截断）。 */
+export declare const DEFAULT_SUBAGENT_TASK_TIMEOUT_MS = 600000;
+/** 每父会话累计子代理配额（非 resume 提交计数；500 避免长会话超过 500 个子会话后被锁死）。 */
+export declare const DEFAULT_SUBAGENT_MAX_TOTAL_PER_PARENT = 500;
+/** 血缘递归深度硬限（不变；入 manifest config 使用户可见可改）。 */
+export declare const DEFAULT_SUBAGENT_MAX_NESTED_DEPTH = 2;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;CAS1B,CAAC;AACX,sGAAoD;AACpD,eAAO,MAAM,mCAAmC,IAAI,CAAC;AACrD,kGAA8C;AAC9C,eAAO,MAAM,gCAAgC,SAAU,CAAC;AACxD,iIAA2D;AAC3D,eAAO,MAAM,qCAAqC,MAAM,CAAC;AACzD,0FAA8C;AAC9C,eAAO,MAAM,iCAAiC,IAAI,CAAC","sourcesContent":["/**\n * 子代理调度器出厂默认值（docs/design/产品默认值清单.md）。\n * 单一定义源：capability manifest（delegate.ts）、runner 装配（subagent-runtime.ts）\n * 与 plugin.json 的 config 声明共用；用户经\n * `<agentDir>/capabilities/builtin.subagent-delegate.json` 覆盖。\n *\n * 2026-10-19 重度并行画像调定：maxConcurrentSubagents 是**每会话**上限（调度器\n * 实例每主会话一个，进程内无全局子代理闸门）；12 = 单会话 1.5×8，20 会话理论峰值\n * 240 个并发子代理（G2 实测进程内簿记约 1.1MB/个，200 并发 ≈220MB），实际瓶颈是\n * provider 限流。大小预算（bytes/maxMessages）不是并发，未调。\n */\nexport const DEFAULT_SUBAGENT_LIMITS = {\n\tmaxConcurrentSubagents: 12,\n\tmaxQueueDepth: 200,\n\tmaxPromptBytes: 65536,\n\tmaxMetadataBytes: 16384,\n\tmaxResultBytes: 524288,\n\tmaxMessages: 2000,\n\tdrainTimeoutMs: 30000,\n\tmaxRetainedRecords: 512,\n} as const;\n/** 单次 `subagent_run` 并行扇出（与 12 并发对齐，避免小任务组被硬拒绝）。 */\nexport const DEFAULT_SUBAGENT_MAX_TASKS_PER_CALL = 8;\n/** 前台阻塞 drain 预算（10 分钟，减少长编码任务被 5 分钟超时截断）。 */\nexport const DEFAULT_SUBAGENT_TASK_TIMEOUT_MS = 600_000;\n/** 每父会话累计子代理配额（非 resume 提交计数；500 避免长会话超过 500 个子会话后被锁死）。 */\nexport const DEFAULT_SUBAGENT_MAX_TOTAL_PER_PARENT = 500;\n/** 血缘递归深度硬限（不变；入 manifest config 使用户可见可改）。 */\nexport const DEFAULT_SUBAGENT_MAX_NESTED_DEPTH = 2;\n"]}

package/dist/defaults.js

@@ -0,0 +1,30 @@
+/**
+ * 子代理调度器出厂默认值（docs/design/产品默认值清单.md）。
+ * 单一定义源：capability manifest（delegate.ts）、runner 装配（subagent-runtime.ts）
+ * 与 plugin.json 的 config 声明共用；用户经
+ * `<agentDir>/capabilities/builtin.subagent-delegate.json` 覆盖。
+ *
+ * 2026-10-19 重度并行画像调定：maxConcurrentSubagents 是**每会话**上限（调度器
+ * 实例每主会话一个，进程内无全局子代理闸门）；12 = 单会话 1.5×8，20 会话理论峰值
+ * 240 个并发子代理（G2 实测进程内簿记约 1.1MB/个，200 并发 ≈220MB），实际瓶颈是
+ * provider 限流。大小预算（bytes/maxMessages）不是并发，未调。
+ */
+export const DEFAULT_SUBAGENT_LIMITS = {
+    maxConcurrentSubagents: 12,
+    maxQueueDepth: 200,
+    maxPromptBytes: 65536,
+    maxMetadataBytes: 16384,
+    maxResultBytes: 524288,
+    maxMessages: 2000,
+    drainTimeoutMs: 30000,
+    maxRetainedRecords: 512,
+};
+/** 单次 `subagent_run` 并行扇出（与 12 并发对齐，避免小任务组被硬拒绝）。 */
+export const DEFAULT_SUBAGENT_MAX_TASKS_PER_CALL = 8;
+/** 前台阻塞 drain 预算（10 分钟，减少长编码任务被 5 分钟超时截断）。 */
+export const DEFAULT_SUBAGENT_TASK_TIMEOUT_MS = 600_000;
+/** 每父会话累计子代理配额（非 resume 提交计数；500 避免长会话超过 500 个子会话后被锁死）。 */
+export const DEFAULT_SUBAGENT_MAX_TOTAL_PER_PARENT = 500;
+/** 血缘递归深度硬限（不变；入 manifest config 使用户可见可改）。 */
+export const DEFAULT_SUBAGENT_MAX_NESTED_DEPTH = 2;
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,sBAAsB,EAAE,EAAE;IAC1B,aAAa,EAAE,GAAG;IAClB,cAAc,EAAE,KAAK;IACrB,gBAAgB,EAAE,KAAK;IACvB,cAAc,EAAE,MAAM;IACtB,WAAW,EAAE,IAAI;IACjB,cAAc,EAAE,KAAK;IACrB,kBAAkB,EAAE,GAAG;CACd,CAAC;AACX,sGAAoD;AACpD,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,CAAC;AACrD,kGAA8C;AAC9C,MAAM,CAAC,MAAM,gCAAgC,GAAG,OAAO,CAAC;AACxD,iIAA2D;AAC3D,MAAM,CAAC,MAAM,qCAAqC,GAAG,GAAG,CAAC;AACzD,0FAA8C;AAC9C,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC","sourcesContent":["/**\n * 子代理调度器出厂默认值（docs/design/产品默认值清单.md）。\n * 单一定义源：capability manifest（delegate.ts）、runner 装配（subagent-runtime.ts）\n * 与 plugin.json 的 config 声明共用；用户经\n * `<agentDir>/capabilities/builtin.subagent-delegate.json` 覆盖。\n *\n * 2026-10-19 重度并行画像调定：maxConcurrentSubagents 是**每会话**上限（调度器\n * 实例每主会话一个，进程内无全局子代理闸门）；12 = 单会话 1.5×8，20 会话理论峰值\n * 240 个并发子代理（G2 实测进程内簿记约 1.1MB/个，200 并发 ≈220MB），实际瓶颈是\n * provider 限流。大小预算（bytes/maxMessages）不是并发，未调。\n */\nexport const DEFAULT_SUBAGENT_LIMITS = {\n\tmaxConcurrentSubagents: 12,\n\tmaxQueueDepth: 200,\n\tmaxPromptBytes: 65536,\n\tmaxMetadataBytes: 16384,\n\tmaxResultBytes: 524288,\n\tmaxMessages: 2000,\n\tdrainTimeoutMs: 30000,\n\tmaxRetainedRecords: 512,\n} as const;\n/** 单次 `subagent_run` 并行扇出（与 12 并发对齐，避免小任务组被硬拒绝）。 */\nexport const DEFAULT_SUBAGENT_MAX_TASKS_PER_CALL = 8;\n/** 前台阻塞 drain 预算（10 分钟，减少长编码任务被 5 分钟超时截断）。 */\nexport const DEFAULT_SUBAGENT_TASK_TIMEOUT_MS = 600_000;\n/** 每父会话累计子代理配额（非 resume 提交计数；500 避免长会话超过 500 个子会话后被锁死）。 */\nexport const DEFAULT_SUBAGENT_MAX_TOTAL_PER_PARENT = 500;\n/** 血缘递归深度硬限（不变；入 manifest config 使用户可见可改）。 */\nexport const DEFAULT_SUBAGENT_MAX_NESTED_DEPTH = 2;\n"]}

package/dist/delegate.d.ts

@@ -7,24 +7,31 @@ export declare const capabilityManifest: {
     readonly apiVersion: "1-draft";
     readonly requiredCapabilities: readonly ["session", "tools"];
     readonly optionalCapabilities: readonly ["agents"];
+    readonly provides: readonly [{
+        readonly id: "agent-forge.agent-task-scheduler";
+        readonly version: 1;
+        readonly kind: "service";
+    }];
     /**
      * 用户可配置默认值（D-044 §6 四层归属的 Profile/capability 配置层）：
      * 经 agent-dir 配置通道 `<agentDir>/capabilities/builtin.subagent-delegate.json`
      * 浅合并覆盖；宿主显式 options 优先级最高；非法值在装载时 fail fast。
      */
     readonly config: {
-        readonly maxConcurrentSubagents: 8;
+        readonly maxConcurrentSubagents: 12;
         readonly maxQueueDepth: 200;
         readonly maxPromptBytes: 65536;
         readonly maxMetadataBytes: 16384;
         readonly maxResultBytes: 524288;
         readonly maxMessages: 2000;
         readonly drainTimeoutMs: 30000;
-        readonly maxRetainedRecords: 256;
-        readonly maxTasksPerCall: 4;
-        readonly taskTimeoutMs: 300000;
+        readonly maxRetainedRecords: 512;
+        readonly maxTasksPerCall: 8;
+        readonly taskTimeoutMs: 600000;
+        readonly maxTotalPerParent: 500;
+        readonly maxNestedDepth: 2;
         readonly runnerMaxProcesses: 0;
-        readonly runnerMaxSessionsPerRunner: 8;
+        readonly runnerMaxSessionsPerRunner: 12;
         readonly runnerIdleTimeoutMs: 300000;
         readonly runnerSweepIntervalMs: 60000;
         readonly runnerEntryAuto: false;
@@ -34,7 +41,7 @@ export interface SubagentDelegateCapabilityOptions {
     /** 宿主可注入调度器 adapter（如 pooled runner adapter）；优先级高于配置驱动的 pooled 装配与共享模式。 */
     adapter?: AgentTaskAdapter;
     limits?: SubagentRuntimeLimitsV1;
-    /** 单次工具调用的并行任务上限（默认 4）与单任务 drain 超时（默认 300000ms）。 */
+    /** 单次工具调用的并行任务上限（默认 8）与单任务 drain 超时（默认 600000ms）。 */
     maxTasksPerCall?: number;
     taskTimeoutMs?: number;
     /**
@@ -79,7 +86,7 @@ export interface SubagentDelegateCapabilityOptions {
     /**
      * Durable 终态持久化（durable replay assembly，2026-10-13 用户裁决）：宿主注入
      * durable 设施（store + writerId，写者租约生命周期由宿主持有），调度器按 `subagent-task:<taskId>` 落库终态
-     * 信封，`subagent_result` 跨进程重启后仍可读回（日志在 `<agentDir>/durable/`，
+     * 信封，`subagent_task`（type `result`）跨进程重启后仍可读回（日志在 `<agentDir>/durable/`，
      * 独立于 sessions 树，主会话删除/清理不波及）。未注入 = 优雅降级为现状（内存
      * 记录 + transcript 落盘，`result()` 回 undefined）；持久化失败不吞终态——错误经
      * drain()/dispose() 的 reject 通道暴露（两处调用点都有 catch 臂）。
@@ -130,9 +137,16 @@ export interface SubagentDelegateTaskProjectionV1 {
     readonly summary?: string;
     /**
      * 子会话 escalate 上抛的有界消息（D-060 S4）：落在父侧下一次工具结果里（这里或
-     * `subagent_result`），父回合不被打断；无积压时省略。
+     * `subagent_task` type `result`），父回合不被打断；无积压时省略。
      */
     readonly escalations?: readonly string[];
+    /**
+     * 任务层结果（任务级拒绝）：子代理以 `subagent_message`（type `refuse`）声明不做该
+     * 任务时随自然成功结算附 `taskOutcome: "refused"`——该拒绝是终局声明；无则省略。
+     */
+    readonly taskOutcome?: "refused";
+    /** 拒绝原因；仅与 taskOutcome 同时出现。 */
+    readonly refusalReason?: string;
     /**
      * 该子会话相关的兄弟消息流量摘录（D-060 裁决 14 父可见性）：from/to 命中的最新
      * 至多 8 条，每条 text 截 256 utf-8 字节；无流量时省略。审计日志在信箱侧，drain
@@ -147,7 +161,7 @@ export interface SubagentDelegateTaskProjectionV1 {
 export interface SubagentDelegateResultV1 {
     readonly tasks: readonly SubagentDelegateTaskProjectionV1[];
 }
-/** 后台委派票据（D-060 S6）：提交即返回，结果稍后经 subagent_result / 摘要注入获得。 */
+/** 后台委派票据（D-060 S6）：提交即返回，结果稍后经 subagent_task（type `result`）/ 摘要注入获得。 */
 export interface SubagentDelegateBackgroundTaskV1 {
     readonly taskId: string;
 }
@@ -156,7 +170,7 @@ export interface SubagentDelegateBackgroundResultV1 {
     readonly tasks: readonly SubagentDelegateBackgroundTaskV1[];
 }
 /**
- * `subagent_cancel` 的返回形状（S4 补充裁决，2026-10-01）：调度器 `cancelById` 的
+ * `subagent_task`（type `cancel`）的返回形状（S4 补充裁决，2026-10-01）：调度器 `cancelById` 的
  * 三态 outcome + 寻址 taskId；cancelled / already_terminal 附调度器最终状态，
  * not_found 不带 status（不抛异常——未知 taskId 是可表达的正常结果）。
  */
@@ -220,7 +234,7 @@ export interface SubagentRoleCatalogResolutionV1 {
 export declare const SESSION_ROLE_STATE_ENTRY: "subagent.roles.state";
 /**
  * 快照里的单个角色：与角色文件同构的**平铺定义** + id（文件形态的 id 来自文件名，
- * 条目里必须自带）。收窄字段平铺为 model/thinkingLevel/tools/mode/systemPromptAppend，
+ * 条目里必须自带）。收窄字段平铺为 model/thinkingLevel/tools/writeScope/mode/systemPromptAppend，
  * 载入内存时仍归一化为 `SubagentDelegateRoleV1`（profile 嵌套形态）。
  */
 export interface SubagentSessionRoleRecordV1 {
@@ -230,7 +244,9 @@ export interface SubagentSessionRoleRecordV1 {
     readonly model?: string;
     readonly thinkingLevel?: string;
     readonly tools?: readonly string[];
+    readonly writeScope?: readonly string[];
     readonly mode?: "readonly" | "full-control";
+    readonly webSearch?: "off" | "auto";
     readonly systemPromptAppend?: string;
     readonly parentView?: boolean;
 }
@@ -239,7 +255,7 @@ export interface SubagentSessionRolesStateV1 {
     readonly version: 1;
     readonly roles: readonly SubagentSessionRoleRecordV1[];
 }
-/** `subagent_role_list`（无 id）的摘要条目：来源 + 一句话说明 + 收窄面有无。 */
+/** `subagent_role`（type `list`，无 id）的摘要条目：来源 + 一句话说明 + 收窄面有无。 */
 export interface SubagentRoleListEntryV1 {
     readonly id: string;
     readonly origin: "disk" | "session";
@@ -250,20 +266,20 @@ export interface SubagentRoleListEntryV1 {
 export interface SubagentRoleListResultV1 {
     readonly roles: readonly SubagentRoleListEntryV1[];
 }
-/** `subagent_role_list({ id })` 的完整定义（含 instructions 与收窄字段，供读-改-写）。 */
+/** `subagent_role`（type `list`，带 `id`）的完整定义（含 instructions 与收窄字段，供读-改-写）。 */
 export interface SubagentRoleDefinitionViewV1 extends SubagentSessionRoleRecordV1 {
     readonly origin: "disk" | "session";
 }
 export interface SubagentRoleViewResultV1 {
     readonly role: SubagentRoleDefinitionViewV1;
 }
-/** `subagent_role_set` 的结果：created/updated + 合并后全部可用角色 id（排序）。 */
+/** `subagent_role`（type `set`）的结果：created/updated + 合并后全部可用角色 id（排序）。 */
 export interface SubagentRoleSetResultV1 {
     readonly id: string;
     readonly status: "created" | "updated";
     readonly roles: readonly string[];
 }
-/** `subagent_role_remove` 的结果：removed + 合并后全部可用角色 id（排序）。 */
+/** `subagent_role`（type `remove`）的结果：removed + 合并后全部可用角色 id（排序）。 */
 export interface SubagentRoleRemoveResultV1 {
     readonly id: string;
     readonly status: "removed";
@@ -344,7 +360,7 @@ export interface SubagentDelegateContextV1 {
     readonly anchors?: readonly SubagentDelegateContextAnchorV1[];
     readonly failedAttempts?: readonly SubagentDelegateContextFailedAttemptV1[];
 }
-/** `subagent_result` 的返回形状：两个来源（调度记录 / 持久化 transcript）共用一个有界信封。 */
+/** `subagent_task`（type `result`）的返回形状：两个来源（调度记录 / 持久化 transcript）共用一个有界信封。 */
 export interface SubagentResultReadResultV1 {
     readonly found: boolean;
     readonly source: "record" | "session";
@@ -370,12 +386,16 @@ export interface SubagentResultReadResultV1 {
         to: string;
         text: string;
     }[];
+    /** 任务层结果（任务级拒绝）；仅调度记录来源携带（transcript 回读无调度记录）。 */
+    readonly taskOutcome?: "refused";
+    /** 拒绝原因；仅与 taskOutcome 同时出现。 */
+    readonly refusalReason?: string;
     /** taskId 已知但尚未结算（后台委派）：稍后再取或带 waitMs 等待。 */
     readonly knownTask?: true;
     /** 未结算任务的当前调度器状态（queued/admitted/running）。 */
     readonly taskStatus?: string;
 }
-/** `subagent_list` 的条目：store 摘要 + 调度器状态富化（有则附）。 */
+/** `subagent_task`（type `list`）的条目：store 摘要 + 调度器状态富化（有则附）。 */
 export interface SubagentSessionListEntryV1 {
     readonly sessionId: string;
     readonly agentRole?: string;