@khorsheed/dsh-local-agent 0.1.0-rc.8 → 0.2.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 变更记录
 
+## 0.2.0-rc.1（2026-09-30）
+
+- **家族折叠：委派工具工厂收进本包**。新增 `./tool-factory` 导出（`mountSubagentDelegationTool` / `subagentToolConfigSchema` / `SubagentToolConfig` / `RESUME_HINT_PREFIX`）——原共享包 `@khorsheed/dsh-local-agent-tool-subagent` 的实现整体迁入，该包随之退役。各 provider 的委派工具改为各自包内的 `./tool` 组合入口（`@khorsheed/dsh-local-agent-kimi/tool` 等），由 agent 预设点名按会话授予，不再挂 profile 根；工具来源标签的 owner 由调用入口传自己包名，工厂不再硬编码。随工厂迁入新增 peer 依赖 `@deepseek-ai/dsh-tools`。
+
 ## 0.1.0-rc.8（2026-09-30）
 
 家族同版联动：加宽 `@deepseek-ai/dsh-*` peer 区间以覆盖宿主 0.2.0（0.2.0 的兼容闸会禁用 peer 区间不覆盖宿主版本的已装插件）。无功能变更。

package/README.en.md

@@ -111,7 +111,7 @@ export function registerCodex(ctx: Context): void {
 
 ### Delegation registry (resume carrier)
 
-The registry also owns the family's **delegation registry**: a per-child-session record of which provider and CLI session a delegation used, plus a per-(parent, provider) FIFO of delegation intents. The family tool (`@khorsheed/dsh-local-agent-tool-subagent`, mounted by each harness bundle's patch) stages exactly one intent per call before `ctx.subagents.start()`, and the owning provider consumes exactly one per start — so fresh and resume rounds stay paired even under parallel delegation. A resume handle (the dsh child session id) resolves through the registry, which rejects a handle naming an unknown child, another parent's session, or the wrong provider; the subagent request descriptor cannot carry the target, so this service is the family-internal carrier. Mappings persist per harness in an append-only `delegations.jsonl` under the harness's scoped home (last line per child session wins), so a resume handle survives a host restart.
+The registry also owns the family's **delegation registry**: a per-child-session record of which provider and CLI session a delegation used, plus a per-(parent, provider) FIFO of delegation intents. The family tool (each provider package's `./tool` composition entry, sharing this package's `./tool-factory` export — the former `@khorsheed/dsh-local-agent-tool-subagent` package retired at the family fold) stages exactly one intent per call before `ctx.subagents.start()`, and the owning provider consumes exactly one per start — so fresh and resume rounds stay paired even under parallel delegation. A resume handle (the dsh child session id) resolves through the registry, which rejects a handle naming an unknown child, another parent's session, or the wrong provider; the subagent request descriptor cannot carry the target, so this service is the family-internal carrier. Mappings persist per harness in an append-only `delegations.jsonl` under the harness's scoped home (last line per child session wins), so a resume handle survives a host restart.
 
 ### Delegation call options (facade)
 

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/local-agent/README.en.md
-packages/local-agent/README.en.md: 131ab524efcb081b0cbd4f27f6bd2b221d58003f
-packages/local-agent/README.md: 16d63a8046557a8f6d7582ec338f41a0f1774110
+packages/local-agent/README.en.md: 94e1222b1d0da755b9d1bdd1cbf3d3561dafa033
+packages/local-agent/README.md: d63cf0d8cceadf5c2b6d159c3c638341358e2b3a

package/README.md

@@ -111,7 +111,7 @@ export function registerCodex(ctx: Context): void {
 
 ### 委派 registry（resume 载体）
 
-registry 还持有家族的**委派 registry**：每个子会话一条记录，记下该委派用的 provider 与 CLI 会话，以及按 (parent, provider) 分组的委派 intent FIFO。家族工具（`@khorsheed/dsh-local-agent-tool-subagent`，由各 harness bundle 的 patch 挂载）在每次调用 `ctx.subagents.start()` 前恰好 stage 一个 intent，归属 provider 每次 start 恰好消费一个——因此即使并行委派，fresh 轮与 resume 轮也能正确配对。resume 轮的句柄（dsh 子会话 id）经 registry 解析，凡是未知子会话、他人 parent 的会话、或错误 provider 的句柄都会被拒绝；subagent 请求 descriptor 无法携带该目标，因此本服务就是家族内部的载体。映射按 harness 持久化在其作用域目录下的 append-only `delegations.jsonl`（同一子会话最后一行生效），resume 句柄因此能跨宿主重启存活。
+registry 还持有家族的**委派 registry**：每个子会话一条记录，记下该委派用的 provider 与 CLI 会话，以及按 (parent, provider) 分组的委派 intent FIFO。家族工具（各 provider 包的 `./tool` 组合入口，实现共享自本包的 `./tool-factory` 导出——原 `@khorsheed/dsh-local-agent-tool-subagent` 已于家族折叠退役）在每次调用 `ctx.subagents.start()` 前恰好 stage 一个 intent，归属 provider 每次 start 恰好消费一个——因此即使并行委派，fresh 轮与 resume 轮也能正确配对。resume 轮的句柄（dsh 子会话 id）经 registry 解析，凡是未知子会话、他人 parent 的会话、或错误 provider 的句柄都会被拒绝；subagent 请求 descriptor 无法携带该目标，因此本服务就是家族内部的载体。映射按 harness 持久化在其作用域目录下的 append-only `delegations.jsonl`（同一子会话最后一行生效），resume 句柄因此能跨宿主重启存活。
 
 ### 委派调用选项（facade）
 

package/lib/client.js

@@ -165,17 +165,17 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var MemberConfiguration_module_css_default = {
-			"back": "pkplGa_back",
-			"triggerLabel": "pkplGa_triggerLabel",
-			"optionLabel": "pkplGa_optionLabel",
+			"actions": "pkplGa_actions",
 			"candidates": "pkplGa_candidates",
-			"fields": "pkplGa_fields",
+			"root": "pkplGa_root",
+			"optionLabel": "pkplGa_optionLabel",
+			"triggerLabel": "pkplGa_triggerLabel",
+			"panel": "pkplGa_panel",
+			"settings": "pkplGa_settings",
 			"menuRow": "pkplGa_menuRow",
+			"back": "pkplGa_back",
 			"check": "pkplGa_check",
-			"settings": "pkplGa_settings",
-			"panel": "pkplGa_panel",
-			"actions": "pkplGa_actions",
-			"root": "pkplGa_root"
+			"fields": "pkplGa_fields"
 		};
 		//#endregion
 		//#region src/client/ModelConfigurationFields.tsx
@@ -6046,12 +6046,12 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			"requestId": string(),
 			"revision": number(),
 			"status": union([
-				literal("cancelled"),
 				literal("pending"),
 				literal("applying"),
 				literal("failed"),
 				literal("unsupported"),
 				literal("applied"),
+				literal("cancelled"),
 				literal("conflict"),
 				literal("locked")
 			]),
@@ -6071,8 +6071,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		let _khorsheed_dsh_local_agent_localAgentGateway_controlMemberInbox_parameter_3$schema$value;
 		const _khorsheed_dsh_local_agent_localAgentGateway_controlMemberInbox_parameter_3$schema = () => _khorsheed_dsh_local_agent_localAgentGateway_controlMemberInbox_parameter_3$schema$value ??= union([
 			_undefined(),
-			literal("done"),
-			literal("cancelled")
+			literal("cancelled"),
+			literal("done")
 		]);
 		let _khorsheed_dsh_local_agent_localAgentGateway_controlMemberInbox_parameter_4$schema$value;
 		const _khorsheed_dsh_local_agent_localAgentGateway_controlMemberInbox_parameter_4$schema = () => _khorsheed_dsh_local_agent_localAgentGateway_controlMemberInbox_parameter_4$schema$value ??= union([_undefined(), string()]);
@@ -6205,10 +6205,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		let _khorsheed_dsh_local_agent_localAgentGateway_followMemberDirectory_result$schema$value;
 		const _khorsheed_dsh_local_agent_localAgentGateway_followMemberDirectory_result$schema = () => _khorsheed_dsh_local_agent_localAgentGateway_followMemberDirectory_result$schema$value ??= object({
 			"status": union([
-				literal("stale"),
-				literal("error"),
 				literal("loading"),
 				literal("ready"),
+				literal("stale"),
+				literal("error"),
 				literal("unsupported")
 			]),
 			"refreshing": boolean(),
@@ -6249,7 +6249,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				"id": string(),
 				"turn": number(),
 				"step": number(),
-				"kind": union([literal("text"), literal("think")]),
+				"kind": union([literal("think"), literal("text")]),
 				"text": string(),
 				"revision": number(),
 				"receivedAt": number()
@@ -6260,8 +6260,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		const _khorsheed_dsh_local_agent_localAgentGateway_followMembers_parameter_0$schema = () => _khorsheed_dsh_local_agent_localAgentGateway_followMembers_parameter_0$schema$value ??= array(object({
 			"memberId": string(),
 			"channel": union([
-				literal("directory"),
 				literal("configuration"),
+				literal("directory"),
 				literal("output")
 			])
 		}));
@@ -6389,10 +6389,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				"channel": literal("directory"),
 				"value": object({
 					"status": union([
-						literal("stale"),
-						literal("error"),
 						literal("loading"),
 						literal("ready"),
+						literal("stale"),
+						literal("error"),
 						literal("unsupported")
 					]),
 					"refreshing": boolean(),
@@ -6434,7 +6434,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 						"id": string(),
 						"turn": number(),
 						"step": number(),
-						"kind": union([literal("text"), literal("think")]),
+						"kind": union([literal("think"), literal("text")]),
 						"text": string(),
 						"revision": number(),
 						"receivedAt": number()
@@ -6446,8 +6446,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				"memberId": string(),
 				"channel": literal("error"),
 				"source": union([
-					literal("directory"),
 					literal("configuration"),
+					literal("directory"),
 					literal("output")
 				]),
 				"message": string()
@@ -6460,10 +6460,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		let _khorsheed_dsh_local_agent_localAgentGateway_followModelDirectory_result$schema$value;
 		const _khorsheed_dsh_local_agent_localAgentGateway_followModelDirectory_result$schema = () => _khorsheed_dsh_local_agent_localAgentGateway_followModelDirectory_result$schema$value ??= object({
 			"status": union([
-				literal("stale"),
-				literal("error"),
 				literal("loading"),
 				literal("ready"),
+				literal("stale"),
+				literal("error"),
 				literal("unsupported")
 			]),
 			"refreshing": boolean(),
@@ -6628,10 +6628,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			"choices": array(string()),
 			"directory": object({
 				"status": union([
-					literal("stale"),
-					literal("error"),
 					literal("loading"),
 					literal("ready"),
+					literal("stale"),
+					literal("error"),
 					literal("unsupported")
 				]),
 				"refreshing": boolean(),
@@ -6790,10 +6790,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		let _khorsheed_dsh_local_agent_localAgentGateway_memberDirectory_result$schema$value;
 		const _khorsheed_dsh_local_agent_localAgentGateway_memberDirectory_result$schema = () => _khorsheed_dsh_local_agent_localAgentGateway_memberDirectory_result$schema$value ??= union([literal(null), object({
 			"status": union([
-				literal("stale"),
-				literal("error"),
 				literal("loading"),
 				literal("ready"),
+				literal("stale"),
+				literal("error"),
 				literal("unsupported")
 			]),
 			"refreshing": boolean(),
@@ -6836,11 +6836,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				"id": string(),
 				"text": string(),
 				"status": union([
-					literal("running"),
-					literal("done"),
-					literal("cancelled"),
 					literal("failed"),
+					literal("cancelled"),
 					literal("queued"),
+					literal("running"),
+					literal("done"),
 					literal("uncertain")
 				]),
 				"createdAt": number(),
@@ -6981,10 +6981,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			"choices": array(string()),
 			"directory": object({
 				"status": union([
-					literal("stale"),
-					literal("error"),
 					literal("loading"),
 					literal("ready"),
+					literal("stale"),
+					literal("error"),
 					literal("unsupported")
 				]),
 				"refreshing": boolean(),
@@ -7038,10 +7038,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		let _khorsheed_dsh_local_agent_localAgentGateway_modelDirectory_result$schema$value;
 		const _khorsheed_dsh_local_agent_localAgentGateway_modelDirectory_result$schema = () => _khorsheed_dsh_local_agent_localAgentGateway_modelDirectory_result$schema$value ??= union([literal(null), object({
 			"status": union([
-				literal("stale"),
-				literal("error"),
 				literal("loading"),
 				literal("ready"),
+				literal("stale"),
+				literal("error"),
 				literal("unsupported")
 			]),
 			"refreshing": boolean(),
@@ -7120,12 +7120,12 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			"requestId": string(),
 			"revision": number(),
 			"status": union([
-				literal("cancelled"),
 				literal("pending"),
 				literal("applying"),
 				literal("failed"),
 				literal("unsupported"),
 				literal("applied"),
+				literal("cancelled"),
 				literal("conflict"),
 				literal("locked")
 			]),
@@ -8277,29 +8277,29 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			document.head.appendChild(tag);
 		}
 		var MemberComposer_module_css_default = {
-			"modelChipLabel": "_7o4e8W_modelChipLabel",
-			"modelPicker": "_7o4e8W_modelPicker",
-			"modelItem": "_7o4e8W_modelItem",
-			"input": "_7o4e8W_input",
-			"frame": "_7o4e8W_frame",
 			"root": "_7o4e8W_root",
+			"error": "_7o4e8W_error",
+			"dock": "_7o4e8W_dock",
+			"modelMenu": "_7o4e8W_modelMenu",
+			"modelItemReset": "_7o4e8W_modelItemReset",
+			"modelItemHint": "_7o4e8W_modelItemHint",
+			"card": "_7o4e8W_card",
+			"frame": "_7o4e8W_frame",
+			"modelPicker": "_7o4e8W_modelPicker",
+			"modelChipLabel": "_7o4e8W_modelChipLabel",
+			"chevron": "_7o4e8W_chevron",
 			"row": "_7o4e8W_row",
 			"header": "_7o4e8W_header",
-			"chevron": "_7o4e8W_chevron",
-			"primary": "_7o4e8W_primary",
-			"modelItemCheck": "_7o4e8W_modelItemCheck",
-			"modelItemReset": "_7o4e8W_modelItemReset",
 			"modelChip": "_7o4e8W_modelChip",
-			"modelMenu": "_7o4e8W_modelMenu",
-			"dockRow": "_7o4e8W_dockRow",
-			"error": "_7o4e8W_error",
-			"modelItemHint": "_7o4e8W_modelItemHint",
-			"dock": "_7o4e8W_dock",
-			"running": "_7o4e8W_running",
-			"chevronOpen": "_7o4e8W_chevronOpen",
 			"modelItemCurrent": "_7o4e8W_modelItemCurrent",
 			"modelItemLabel": "_7o4e8W_modelItemLabel",
-			"card": "_7o4e8W_card"
+			"running": "_7o4e8W_running",
+			"modelItem": "_7o4e8W_modelItem",
+			"modelItemCheck": "_7o4e8W_modelItemCheck",
+			"chevronOpen": "_7o4e8W_chevronOpen",
+			"dockRow": "_7o4e8W_dockRow",
+			"input": "_7o4e8W_input",
+			"primary": "_7o4e8W_primary"
 		};
 		//#endregion
 		//#region src/client/MemberComposer.tsx
@@ -9360,30 +9360,30 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			document.head.appendChild(tag);
 		}
 		var ProviderAuthBlock_module_css_default = {
-			"credentialDot": "On5p7W_credentialDot",
-			"rowName": "On5p7W_rowName",
+			"status": "On5p7W_status",
 			"retryButton": "On5p7W_retryButton",
-			"rowCard": "On5p7W_rowCard",
-			"title": "On5p7W_title",
-			"codeInput": "On5p7W_codeInput",
-			"dotOn": "On5p7W_dotOn",
-			"intro": "On5p7W_intro",
+			"credentialDot": "On5p7W_credentialDot",
+			"promptText": "On5p7W_promptText",
 			"rowTag": "On5p7W_rowTag",
-			"rowActions": "On5p7W_rowActions",
-			"dotPending": "On5p7W_dotPending",
-			"status": "On5p7W_status",
-			"rows": "On5p7W_rows",
-			"logoutButton": "On5p7W_logoutButton",
+			"rowCard": "On5p7W_rowCard",
+			"rowName": "On5p7W_rowName",
 			"openPage": "On5p7W_openPage",
+			"logoutButton": "On5p7W_logoutButton",
+			"rowPending": "On5p7W_rowPending",
+			"dotOn": "On5p7W_dotOn",
 			"section": "On5p7W_section",
-			"loginPrompt": "On5p7W_loginPrompt",
-			"promptText": "On5p7W_promptText",
 			"dotOff": "On5p7W_dotOff",
-			"loginButton": "On5p7W_loginButton",
-			"rowIdentity": "On5p7W_rowIdentity",
 			"rowHead": "On5p7W_rowHead",
+			"rowActions": "On5p7W_rowActions",
+			"title": "On5p7W_title",
+			"loginButton": "On5p7W_loginButton",
+			"loginPrompt": "On5p7W_loginPrompt",
+			"codeInput": "On5p7W_codeInput",
+			"rows": "On5p7W_rows",
+			"intro": "On5p7W_intro",
+			"dotPending": "On5p7W_dotPending",
 			"rosterError": "On5p7W_rosterError",
-			"rowPending": "On5p7W_rowPending"
+			"rowIdentity": "On5p7W_rowIdentity"
 		};
 		//#endregion
 		//#region src/client/ProviderAuthBlock.tsx
@@ -9656,10 +9656,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			document.head.appendChild(tag);
 		}
 		var AuthStatusDot_module_css_default = {
-			"credentialDot": "OFjNUG_credentialDot",
 			"dotOn": "OFjNUG_dotOn",
-			"dotPending": "OFjNUG_dotPending",
-			"dotOff": "OFjNUG_dotOff"
+			"dotOff": "OFjNUG_dotOff",
+			"credentialDot": "OFjNUG_credentialDot",
+			"dotPending": "OFjNUG_dotPending"
 		};
 		//#endregion
 		//#region src/client/AuthStatusDot.tsx
@@ -9685,18 +9685,18 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			document.head.appendChild(tag);
 		}
 		var MemberInboxView_module_css_default = {
-			"list": "Qhm0ea_list",
-			"iconAction": "Qhm0ea_iconAction",
-			"notice": "Qhm0ea_notice",
-			"recovery": "Qhm0ea_recovery",
+			"lead": "Qhm0ea_lead",
+			"row": "Qhm0ea_row",
 			"action": "Qhm0ea_action",
-			"root": "Qhm0ea_root",
-			"panel": "Qhm0ea_panel",
 			"reconcile": "Qhm0ea_reconcile",
 			"header": "Qhm0ea_header",
-			"row": "Qhm0ea_row",
-			"lead": "Qhm0ea_lead",
+			"notice": "Qhm0ea_notice",
+			"list": "Qhm0ea_list",
+			"iconAction": "Qhm0ea_iconAction",
+			"root": "Qhm0ea_root",
+			"recovery": "Qhm0ea_recovery",
 			"preview": "Qhm0ea_preview",
+			"panel": "Qhm0ea_panel",
 			"toggle": "Qhm0ea_toggle"
 		};
 		//#endregion

package/lib/tool-factory.js

@@ -0,0 +1,256 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/tool-factory.js
+/**
+* The family-owned delegation-tool factory: the model-facing subagent tool
+* over one configured `ctx.subagents` provider, replacing the official
+* tool-subagent rows in the harness bundles. The schema is the official subset
+* (`description`/`prompt`) plus an optional `resume` handle: the dsh child
+* session id returned by the first delegation's result text. A resumed call
+* continues the SAME CLI conversation instead of starting a fresh one — the
+* family providers spawn their CLI's resume command (kimi `-S`, claude
+* `--resume`, codex `exec resume`) under the harness scoped home, appending
+* the new round into the same dsh child session.
+*
+* The resume target never travels inside the prompt: task text is untrusted,
+* and a forged handle embedded there would hijack another session's context.
+* The tool instead carries the handle as a first-class `resume` parameter and
+* resolves it through the localAgent service, which rejects any handle that
+* does not name a delegation recorded for THIS parent session and provider.
+* Continuation rounds still go through `ctx.subagents.start()`, so lifecycle
+* events (`subagent/start`/`subagent/end`) and the standard 子代理 surface are
+* unchanged.
+*
+* This module used to ship as the standalone companion package
+* `@khorsheed/dsh-local-agent-tool-subagent` (0.1.x); the family fold moved it
+* into the core package as the `./tool-factory` export (the worktrees 0.3.0 /
+* room 0.2.0 pattern, one level down: the mountable row is each PROVIDER's own
+* `./tool` composition entry, which binds its provider/toolName defaults and
+* passes its package name as the tool-origin owner). `local-agent-dsh`
+* consumes the same factory for its settings-driven dynamic `subagent_dsh`
+* mount. The factory itself is never a loader row.
+*
+* @module @khorsheed/dsh-local-agent/tool-factory
+*/
+/**
+* Tag the model-visible tool with its origin (AGENTS.md § Tool origin tagging;
+* seam S12): the capability catalog reads this `Symbol.for`-keyed tag back
+* through `ctx.tools.get()`. This factory registers on behalf of every family
+* provider, so the owner arrives as a PARAMETER — the calling entry's own
+* package identity — never a hardcoded package name. The tag is host-side
+* only and never travels on the model wire.
+*/
+const definePluginTool = (def, owner) => Object.assign(def, { [Symbol.for("dsh.tool.origin")]: {
+	channel: "plugin",
+	owner
+} });
+/**
+* Model-visible self-description appended to a FRESH delegation's result, so
+* the model can continue the same conversation in a later round. Pinned
+* verbatim; the resume tool's `resume` parameter carries the handle.
+*/
+const RESUME_HINT_PREFIX = "追问请带 resume=\"";
+/**
+* The Config schema of a provider's `./tool` composition entry: every field
+* optional, defaulting to the CALLING provider's own values, so a preset row
+* needs no config (`- id: tool-subagent-kimi / name:
+* '@khorsheed/dsh-local-agent-kimi/tool'` mounts the kimi delegation tool).
+*
+* Bare `z` return annotation: `z<Config>` fails schemastery 3.18.4's variance
+* under exactOptionalPropertyTypes (TS2375) and dropping the annotation trips
+* TS2742; the interface stays the apply signature's contract.
+*/
+function subagentToolConfigSchema(provider, toolName) {
+	return z.object({
+		provider: z.string().default(provider),
+		toolName: z.string().default(toolName)
+	});
+}
+/** Render text blocks from the canonical JSON block array without trusting arbitrary values. */
+function outputValueText(values) {
+	return values.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value) && value.type === "text" && typeof value.text === "string").map((value) => value.text).join("");
+}
+/** A non-`completed` stop reason means the child did not finish cleanly. */
+function stopReasonError(result) {
+	switch (result.stopReason) {
+		case "completed": return;
+		case "aborted": return "subagent run was cancelled";
+		case "error": return result.diagnostic === void 0 ? "subagent run failed" : `subagent run failed: ${result.diagnostic}`;
+		case "max-tokens": return "subagent run hit its token limit before finishing";
+		case "refusal": return "subagent declined the task";
+		default: return `subagent run ended abnormally (${String(result.stopReason)})`;
+	}
+}
+/**
+* Fuse a caller-owned controller with the tool execution's signal so EITHER
+* abort cancels the run — the same shape the facade's tracked controller
+* uses. The active-delegation registry's stop lever aborts the controller;
+* the tool's own execution abort flows through the execution signal.
+*/
+function fusedSignal(controller, caller) {
+	return caller === void 0 ? controller.signal : AbortSignal.any([controller.signal, caller]);
+}
+/**
+* Append the child's preserved partial answer to a stop-reason error so a
+* truncated or cancelled child's real text still reaches the parent model.
+* @param error - the stop-reason headline.
+* @param output - the child's selected output (`SubagentResult.output`).
+* @returns the headline, extended with the partial text when any exists.
+*/
+function withPartialText(error, output) {
+	const text = output.filter((block) => block.type === "text").map((block) => block.text).join("");
+	return text.length === 0 ? error : `${error}\nPartial output before the run ended:\n${text}`;
+}
+/**
+* Collect and release one foreground run without letting disposal replace an
+* independent result failure.
+*/
+async function settleForegroundRun(run) {
+	const [execution] = await Promise.allSettled([run.result.then((result) => {
+		const error = stopReasonError(result);
+		if (error !== void 0) throw new Error(withPartialText(error, result.output));
+		return {
+			kind: "foreground",
+			runId: run.id,
+			output: result.output
+		};
+	})]);
+	const [disposal] = await Promise.allSettled([Promise.resolve().then(() => run.dispose())]);
+	if (execution.status === "rejected") {
+		if (disposal.status === "rejected") throw new AggregateError([execution.reason, disposal.reason], `subagent run failed: ${String(execution.reason)}; dispose failed: ${String(disposal.reason)}`);
+		throw execution.reason;
+	}
+	if (disposal.status === "rejected") throw disposal.reason;
+	return execution.value;
+}
+/**
+* Model-facing wording for the family CLI providers, which never inherit the
+* parent's conversation (they are fresh CLI processes under a scoped home).
+*/
+function familyWording() {
+	return {
+		description: "Delegate a self-contained task to a local coding-agent CLI (separate process, its own scoped home) so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. To continue the same CLI conversation in a later round, pass the child session id returned by the first result as `resume`. This is the one-shot path — it fits a task you will not revisit. When you expect to work with the SAME agent over several rounds (review → fix → re-review style iteration) and the `room_invite` tool is available, prefer inviting it as a named room member instead: name it by its function (e.g. \"design-review\", \"restart-test\") so later rounds can address it by role and reuse the context it has accumulated.",
+		promptDescription: "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. Never embed a resume handle inside this text.",
+		resumeDescription: "Optional dsh child session id returned by the first delegation's result text, to continue that same CLI conversation in a later round. Omit for a fresh delegation. Never embed the handle inside `prompt` — pass it here."
+	};
+}
+/**
+* Mount the family delegation tool on one provider: register the
+* model-visible tool while the provider is registered, mirroring provider
+* lifecycle (sibling load order and HMR replacement can change provider
+* availability while the calling fiber stays active).
+* @param ctx - the calling entry's plugin context (a preset-scope mount, or
+* local-agent-dsh's toggle-owned dynamic plugin).
+* @param config - resolved provider/toolName pair.
+* @param owner - the calling package's own name, stamped as the tool-origin
+* owner (never hardcoded here — this factory serves every family provider).
+*/
+function mountSubagentDelegationTool(ctx, config, owner) {
+	const toolName = config.toolName ?? "subagent";
+	const wording = familyWording();
+	let disposeTool;
+	const mount = () => {
+		disposeTool = ctx.tools.register(definePluginTool(defineTool({
+			name: toolName,
+			description: wording.description,
+			parameters: {
+				description: {
+					type: "string",
+					required: true,
+					description: "A short (3-5 word) description of the delegated task, for display."
+				},
+				prompt: {
+					type: "string",
+					required: true,
+					description: wording.promptDescription
+				},
+				resume: {
+					type: "string",
+					description: wording.resumeDescription
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						kind: {
+							type: "string",
+							required: true,
+							const: "foreground"
+						},
+						runId: {
+							type: "string",
+							required: true
+						},
+						output: {
+							type: "array",
+							required: true,
+							items: { type: "json" }
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: outputValueText(value.output)
+				}]
+			},
+			isConcurrencySafe: () => true,
+			async execute(args, exec) {
+				const parent = exec.agent;
+				if (!parent) throw new Error("subagent tool requires a calling agent (exec.agent was undefined)");
+				const parentSessionId = parent.session.id;
+				const resumeHandle = args.resume;
+				const resume = resumeHandle === void 0 ? void 0 : ctx.localAgent.resolveDelegation(resumeHandle, {
+					provider: config.provider,
+					parentSessionId
+				});
+				if (resumeHandle === void 0) ctx.localAgent.stageDelegationIntent(parentSessionId, config.provider, { kind: "fresh" });
+				else if (resume !== void 0) {
+					await ctx.localAgent.ensureChildLive?.(resumeHandle);
+					ctx.localAgent.stageDelegationIntent(parentSessionId, config.provider, {
+						kind: "resume",
+						childSessionId: resumeHandle,
+						cliSessionId: resume.cliSessionId
+					});
+				}
+				const request = {
+					label: args.description,
+					prompt: [{
+						type: "text",
+						text: args.prompt
+					}],
+					parent
+				};
+				const controller = new AbortController();
+				const run = await ctx.subagents.start(config.provider, {
+					...request,
+					signal: fusedSignal(controller, exec.signal)
+				});
+				const registry = ctx.localAgent;
+				if (typeof registry.trackDelegationRun === "function") registry.trackDelegationRun(String(run.id), run, () => controller.abort());
+				const settled = await settleForegroundRun(run);
+				if (resume === void 0) return {
+					...settled,
+					output: [...settled.output, {
+						type: "text",
+						text: `${RESUME_HINT_PREFIX}${run.id}"`
+					}]
+				};
+				return settled;
+			}
+		}), owner));
+	};
+	ctx.on("subagent/provider-added", (provider) => {
+		if (provider.name === config.provider && disposeTool === void 0) mount();
+	});
+	ctx.on("subagent/provider-removed", (name) => {
+		if (name !== config.provider || disposeTool === void 0) return;
+		disposeTool();
+		disposeTool = void 0;
+	});
+	if (ctx.subagents.getProvider(config.provider) !== void 0) mount();
+	else ctx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${toolName}" tool will register when it appears`);
+}
+//#endregion
+export { RESUME_HINT_PREFIX, mountSubagentDelegationTool, subagentToolConfigSchema };