@qilin-agent/tool-subagent 3.1.3 → 3.1.5

package/README.i18n.yaml

@@ -5,117 +5,117 @@
 /:
   en: c6db6e2344a91be8
   zh: 4febc8331d506a22
-/qilin-tool-subagent:
-  en: 124c70502cce9bc1
-  zh: 4b4a0dcec9b86bbe
-/qilin-tool-subagent/summary:
+/qilin-agent-tool-subagent:
+  en: d64c585d315ee220
+  zh: 72cf6607cdf6d31a
+/qilin-agent-tool-subagent/summary:
   en: 04da983479776bfa
   zh: 17b955b0390dc448
-/qilin-tool-subagent/table-of-contents:
+/qilin-agent-tool-subagent/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
-/qilin-tool-subagent/use-this-package:
-  en: 3248a28bba2ef809
-  zh: 807cc32c49fcb0cb
-/qilin-tool-subagent/use-this-package/minimal-configuration:
-  en: 0dcc3c461eea237d
-  zh: 5684463df5efbba6
-/qilin-tool-subagent/use-this-package/foreground-and-background-modes:
+/qilin-agent-tool-subagent/use-this-package:
+  en: 93f1701f5209ecb5
+  zh: 6310fd012400aead
+/qilin-agent-tool-subagent/use-this-package/minimal-configuration:
+  en: 00a36ae48c406e0c
+  zh: 4b6082f6a4592492
+/qilin-agent-tool-subagent/use-this-package/foreground-and-background-modes:
   en: 8e7319bc2887ae5c
   zh: 87d5abdfbe7562df
-/qilin-tool-subagent/use-this-package/selecting-a-child-llm:
+/qilin-agent-tool-subagent/use-this-package/selecting-a-child-llm:
   en: 484bf4ed5996539f
   zh: dcb461e031d435c4
-/qilin-tool-subagent/understand-the-implementation:
+/qilin-agent-tool-subagent/understand-the-implementation:
   en: 6ce5f749256a7e6c
   zh: a4f2adb04a70d9cf
-/qilin-tool-subagent/understand-the-implementation/design-concept:
+/qilin-agent-tool-subagent/understand-the-implementation/design-concept:
   en: 5ceacfed4ea0c648
   zh: 005284534923d854
-/qilin-tool-subagent/understand-the-implementation/foreground-settlement:
+/qilin-agent-tool-subagent/understand-the-implementation/foreground-settlement:
   en: ccb36af6884ec89f
   zh: 41e9aa6d3cd75a41
-/qilin-tool-subagent/understand-the-implementation/background-routes:
+/qilin-agent-tool-subagent/understand-the-implementation/background-routes:
   en: dfd6306019a63bea
   zh: 5055b66e19885e8d
-/qilin-tool-subagent/understand-the-implementation/context-sensitive-wording:
+/qilin-agent-tool-subagent/understand-the-implementation/context-sensitive-wording:
   en: 1733728ac5aa6bb0
   zh: 341ffc6e21a289af
-/qilin-tool-subagent/understand-the-implementation/source-map:
+/qilin-agent-tool-subagent/understand-the-implementation/source-map:
   en: 1f52c5f5c7caf04a
   zh: dba288fd0cf51e5d
-/qilin-tool-subagent/further-exploration:
-  en: 4d76f17d7ff95960
-  zh: 9d6eecba80c5912a
-/qilin-tool-subagent/model-experience:
+/qilin-agent-tool-subagent/further-exploration:
+  en: 089b32fdb70fbf87
+  zh: 18c873bfec2611f5
+/qilin-agent-tool-subagent/model-experience:
   en: 215e7ba838619b7b
   zh: a311da3843709f90
-/qilin-tool-subagent/model-experience/tool-schema:
+/qilin-agent-tool-subagent/model-experience/tool-schema:
   en: e4c7376d4f29dbd5
   zh: 6b7a9eaf69c9ea53
-/qilin-tool-subagent/model-experience/tool-schema/what-the-model-sees:
-  en: 5139cb3de9c8d0e3
-  zh: 5e7baea85692f1f9
-/qilin-tool-subagent/model-experience/tool-schema/token-effect:
+/qilin-agent-tool-subagent/model-experience/tool-schema/what-the-model-sees:
+  en: 8fc9f31c6b1d3d40
+  zh: 55e3fb12fba0be26
+/qilin-agent-tool-subagent/model-experience/tool-schema/token-effect:
   en: 1aa53b7a4c24cc25
   zh: bebd5c5ce6443259
-/qilin-tool-subagent/model-experience/tool-schema/kv-cache-effect:
+/qilin-agent-tool-subagent/model-experience/tool-schema/kv-cache-effect:
   en: 46f736c6c389052a
   zh: a7765541030e9104
-/qilin-tool-subagent/model-experience/model-selection-and-discovery:
+/qilin-agent-tool-subagent/model-experience/model-selection-and-discovery:
   en: a4ca31b9cbacda6b
   zh: 91ac3e0784a14697
-/qilin-tool-subagent/model-experience/model-selection-and-discovery/what-the-model-sees:
+/qilin-agent-tool-subagent/model-experience/model-selection-and-discovery/what-the-model-sees:
   en: 1c9dd328eaf96683
   zh: 3be88d3b00f51cfa
-/qilin-tool-subagent/model-experience/model-selection-and-discovery/token-effect:
+/qilin-agent-tool-subagent/model-experience/model-selection-and-discovery/token-effect:
   en: 8137e72f630f0190
   zh: 73b1d9374b6cbccd
-/qilin-tool-subagent/model-experience/model-selection-and-discovery/kv-cache-effect:
+/qilin-agent-tool-subagent/model-experience/model-selection-and-discovery/kv-cache-effect:
   en: 7dc47a34d5574fbd
   zh: bd7bd2a4da2f8ae2
-/qilin-tool-subagent/model-experience/system-prompt:
+/qilin-agent-tool-subagent/model-experience/system-prompt:
   en: cf78b9dd5596495f
   zh: bd44560f8c2435e8
-/qilin-tool-subagent/model-experience/system-prompt/what-the-model-sees:
+/qilin-agent-tool-subagent/model-experience/system-prompt/what-the-model-sees:
   en: 875f8a89292dde21
   zh: 670f911b0a149690
-/qilin-tool-subagent/model-experience/system-prompt/what-the-model-sees/tool-guidance-section:
+/qilin-agent-tool-subagent/model-experience/system-prompt/what-the-model-sees/tool-guidance-section:
   en: 82b3cd08b3961c98
   zh: bdc2a34bcea16cac
-/qilin-tool-subagent/model-experience/system-prompt/token-effect:
+/qilin-agent-tool-subagent/model-experience/system-prompt/token-effect:
   en: ed03868e8f551001
   zh: 53c10b979a48cf9b
-/qilin-tool-subagent/model-experience/system-prompt/kv-cache-effect:
+/qilin-agent-tool-subagent/model-experience/system-prompt/kv-cache-effect:
   en: 5f2491d0ee8f440c
   zh: 14c06b9fe7096e09
-/qilin-tool-subagent/model-experience/foreground-result:
+/qilin-agent-tool-subagent/model-experience/foreground-result:
   en: d83f1f25a3719c54
   zh: 445ca808e28dc936
-/qilin-tool-subagent/model-experience/foreground-result/what-the-model-sees:
+/qilin-agent-tool-subagent/model-experience/foreground-result/what-the-model-sees:
   en: 7e5d19839fa69495
   zh: 0e7ff0d92571ec60
-/qilin-tool-subagent/model-experience/foreground-result/token-effect:
+/qilin-agent-tool-subagent/model-experience/foreground-result/token-effect:
   en: 995810727b29f85f
   zh: 4ede7b437091d6ee
-/qilin-tool-subagent/model-experience/foreground-result/kv-cache-effect:
+/qilin-agent-tool-subagent/model-experience/foreground-result/kv-cache-effect:
   en: f5d5f97a153f7c70
   zh: 3d6bc05b9eadfbc2
-/qilin-tool-subagent/model-experience/background-result:
+/qilin-agent-tool-subagent/model-experience/background-result:
   en: 3f23f9211197b0b9
   zh: 8cff3c78249b66ff
-/qilin-tool-subagent/model-experience/background-result/what-the-model-sees:
+/qilin-agent-tool-subagent/model-experience/background-result/what-the-model-sees:
   en: d2ba2d8a3e88478d
   zh: dee910d1d271f75c
-/qilin-tool-subagent/model-experience/background-result/token-effect:
+/qilin-agent-tool-subagent/model-experience/background-result/token-effect:
   en: 3c67cdb1cbf53647
   zh: bfed5f2945a79c9d
-/qilin-tool-subagent/model-experience/background-result/kv-cache-effect:
+/qilin-agent-tool-subagent/model-experience/background-result/kv-cache-effect:
   en: f5d5f97a153f7c70
   zh: 3d6bc05b9eadfbc2
-/qilin-tool-subagent/known-limitations-and-deferred-work:
+/qilin-agent-tool-subagent/known-limitations-and-deferred-work:
   en: 8482d967fe854d08
   zh: 4e1457ae659f4f28
-/qilin-tool-subagent/known-limitations-and-deferred-work/dev-note:
+/qilin-agent-tool-subagent/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

package/README.md

@@ -25,6 +25,8 @@ Use this package to give an agent a named tool that delegates work to a configur
 <a id="use-this-package"></a>
 ## Use this package
 
+The optional `cwd` argument selects the child's initial working directory. Relative paths resolve against the caller's current directory; omission inherits it. Existing children retain their own directories when the caller changes directory.
+
 Mount one instance per delegation target, each with a distinct `toolName`. The tool exists exactly while its provider does, so sibling load order and provider reloads never strand it.
 
 ### Minimal configuration

package/README.zh.md

@@ -25,6 +25,8 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
+可选参数 `cwd` 选择子级的初始工作目录。相对路径以调用者当前目录解析；省略时继承该目录。调用者切换目录时，已有子级保留自己的目录。
+
 每个委派目标挂载一个实例，且每个实例的 `toolName` 必须不同。工具与其提供方同时存在、同时消失，因此同级加载顺序与提供方重新加载都不会让工具悬空。
 
 ### 最小配置

package/lib/index.js

@@ -2,7 +2,7 @@ import z from "@qilin-agent/schemastery";
 import { scopeChainOf, scopeOf } from "@qilin-agent/scope";
 import { defineTool } from "@qilin-agent/tools";
 import { SessionSeq } from "@qilin-agent/session";
-import { assertSubagentMaxDepth, parentAgentOptionsForDelegation, settleRun } from "@qilin-agent/subagent";
+import { assertSubagentMaxDepth, parentAgentOptionsForDelegation } from "@qilin-agent/subagent";
 import { ReasoningEffortId } from "@qilin-agent/llm";
 import { z as z$1 } from "zod";
 z.object({
@@ -236,10 +236,8 @@ function recordSubagentModelSelection(projections, session, allowedModels) {
 /**
 * Model-facing delegation through one configured `ctx.subagents` provider.
 * Provider lifecycle controls tool registration and context-sensitive schema
-* wording. Foreground calls always dispose the run after collection.
-* Background policy is selected by this plugin's configuration: one-shot
-* calls own a plain Task, while continuable calls use
-* `ctx.subagents.startContinuable()`.
+* wording. Every delegation starts a managed activation and returns its child
+* id; the subagent runtime owns result delivery and resource cleanup.
 * @module @qilin-agent/tool-subagent
 */
 const name = "tool-subagent";
@@ -249,12 +247,11 @@ const inject = [
 	"systemPrompt",
 	"sessionProjections"
 ];
+const delegationTools = /* @__PURE__ */ new Set();
 const Config = z.object({
 	provider: z.string().required(),
 	toolName: z.string().default("subagent"),
 	modelSelectionSettings: z.boolean().default(false),
-	enableRunInBackground: z.boolean().default(true),
-	backgroundMode: z.union(["one-shot", "continuable"]).default("one-shot"),
 	agentOptions: z.object({
 		provider: z.string(),
 		model: z.string(),
@@ -268,67 +265,6 @@ const Config = z.object({
 	}).default(void 0),
 	maxDepth: z.union([z.natural().max(Number.MAX_SAFE_INTEGER), z.const("provider-managed")])
 });
-/** 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("");
-}
-/** Settle pending startup without rejecting the task producer contract. */
-async function settleStart(start, signal) {
-	try {
-		return await settleRun(await start);
-	} catch (error) {
-		return signal.aborted && !(error instanceof AggregateError) ? { status: "killed" } : {
-			status: "failed",
-			detail: String(error)
-		};
-	}
-}
-/** 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 "subagent run failed";
-		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)})`;
-	}
-}
-/**
-* Append provider-authored failure detail and the child's preserved partial
-* answer to a stop-reason error, keeping diagnostic text separate from the
-* child's assistant output.
-* @param error - the stop-reason headline.
-* @param result - the child's terminal result.
-* @returns the headline, diagnostic, and partial text that are present.
-*/
-function withDiagnosticAndPartialText(error, result) {
-	const diagnostic = result.diagnostic === void 0 ? "" : `\nDiagnostic: ${result.diagnostic}`;
-	const text = result.output.filter((block) => block.type === "text").map((block) => block.text).join("");
-	return `${error}${diagnostic}${text.length === 0 ? "" : `\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(withDiagnosticAndPartialText(error, result));
-		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 from the provider's conversation-history descriptor
 * ({@link SubagentProvider.inheritsParentContext}).
@@ -347,18 +283,10 @@ function providerWording(inheritsConversation) {
 		promptDescription: "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
 	};
 	return {
-		description: "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — 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.",
+		description: "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps.",
 		promptDescription: "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
 	};
 }
-/** Resolve the model's optional scheduling request into one execution route. */
-function resolveDelegationRun(request, options) {
-	if (!options.backgroundEnabled) {
-		if (request.run_in_background === true) throw new Error("run_in_background is disabled for this tool instance (enableRunInBackground: false)");
-		return { runInBackground: false };
-	}
-	return { runInBackground: request.run_in_background ?? options.continuable };
-}
 /**
 * Install one delegation-tool composition.
 * @param ctx - Context that owns the registrations.
@@ -368,8 +296,6 @@ function resolveDelegationRun(request, options) {
 function apply(ctx, config, session) {
 	if (config.maxDepth !== "provider-managed") assertSubagentMaxDepth(config.maxDepth);
 	if (config.toolFilter !== void 0 && config.toolFilter.allow === void 0 && config.toolFilter.deny === void 0) throw new Error("tool-subagent: `toolFilter` is configured but names neither `allow` nor `deny` — remove the key or fill the filter");
-	const backgroundEnabled = config.enableRunInBackground !== false;
-	const continuable = (config.backgroundMode ?? "one-shot") === "continuable";
 	const toolName = config.toolName ?? "subagent";
 	const modelSelectionCapable = config.modelSelectionSettings === true;
 	ctx.sessionProjections.register(subagentModelSelectionProjectionDefinition);
@@ -377,7 +303,6 @@ function apply(ctx, config, session) {
 		if (ctx.subagents.resolveMaxDepth(config.maxDepth) !== void 0 && !subagentProvider.capabilities.depthLimit) throw new Error(`tool-subagent: provider "${subagentProvider.name}" cannot enforce maxDepth (no depthLimit capability) — set maxDepth: 'provider-managed' to leave the recursion budget to the provider`);
 		if (config.agentOptions !== void 0 && !subagentProvider.capabilities.agentOptions) throw new Error(`tool-subagent: provider "${subagentProvider.name}" does not support child agentOptions`);
 		if (modelSelectionCapable && !subagentProvider.capabilities.agentOptions) throw new Error(`tool-subagent: provider "${subagentProvider.name}" does not support child model selection`);
-		if (continuable && subagentProvider.prepareContinuable === void 0) throw new Error(`tool-subagent: provider "${subagentProvider.name}" does not support \`backgroundMode: continuable\``);
 	};
 	ctx.on("subagent/provider-added", (subagentProvider) => {
 		if (subagentProvider.name === config.provider) assertSubagentProviderConfiguration(subagentProvider);
@@ -393,173 +318,114 @@ function apply(ctx, config, session) {
 			const wording = providerWording(subagentProvider.inheritsParentContext);
 			const providerRouteDefaults = subagentProvider.agentRouteDefaults;
 			const choiceDescription = !modelSelectionEnabled ? "" : (providerRouteDefaults !== void 0 ? " Child LLM selection is optional. Omit `provider`, `model`, and `reasoning_effort` to use configured child defaults and this provider's route defaults. Supply `provider` and `model` together after using `list_subagent_models` to inspect advertised routes and efforts. Changing the effective route without naming an effort uses the selected model's default effort." : " Child LLM selection is optional. Omit `provider`, `model`, and `reasoning_effort` to use configured child defaults and inherit compatible missing values from the parent Agent. Supply `provider` and `model` together after using `list_subagent_models` to inspect advertised routes and efforts. Changing the effective route without naming an effort uses the selected model's default effort.") + (subagentProvider.inheritsParentContext ? " Changing the route can prevent provider-side reuse of the inherited conversation prefix." : "");
-			mounted = {
-				subagentProvider,
-				disposeTool: runtimeCtx.tools.register(defineTool({
-					name: toolName,
-					description: wording.description + (backgroundEnabled ? continuable ? " This tool runs in the background by default, immediately returns a durable subagent id, and keeps the child conversation available for later turns. When that run settles, the runtime sends the parent a notice containing its outcome and any final assistant message; `send_message` steers the child's nearest step while it is running and starts or resumes a turn while it is inactive. Set `run_in_background: false` only when your next action depends on receiving the result." : " This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`." : " This call waits for the subagent and returns its result.") + choiceDescription,
-					parameters: {
-						description: {
+			const definition = defineTool({
+				name: toolName,
+				description: wording.description + " This tool starts an independently managed subagent and immediately returns its id. The runtime notifies you when it finishes." + (subagentProvider.prepareContinuable !== void 0 ? " The child reports results with `send_message`; use `send_message` to steer it while running or continue its conversation after it finishes." : " The completion notice includes its final answer. This backend does not accept follow-up messages.") + choiceDescription,
+				parameters: {
+					cwd: {
+						type: "string",
+						description: "Initial child working directory. Relative paths use your current directory; omitted inherits it. Later directory changes in either agent are independent."
+					},
+					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
+					},
+					...modelSelectionEnabled ? {
+						provider: {
 							type: "string",
-							required: true,
-							description: "A short (3-5 word) description of the delegated task, for display."
+							description: providerRouteDefaults !== void 0 ? "LLM provider route for the child. Supply together with model; omit both to use configured child defaults or this provider's route defaults." : "LLM provider route for the child. Supply together with model; omit both to use configured child defaults or inherit the parent route."
 						},
-						prompt: {
+						model: {
 							type: "string",
-							required: true,
-							description: wording.promptDescription
+							description: providerRouteDefaults !== void 0 ? "Model id interpreted by provider. Supply together with provider; omit both to use configured child defaults or this provider's route defaults." : "Model id interpreted by provider. Supply together with provider; omit both to use configured child defaults or inherit the parent route."
 						},
-						...modelSelectionEnabled ? {
-							provider: {
-								type: "string",
-								description: providerRouteDefaults !== void 0 ? "LLM provider route for the child. Supply together with model; omit both to use configured child defaults or this provider's route defaults." : "LLM provider route for the child. Supply together with model; omit both to use configured child defaults or inherit the parent route."
-							},
-							model: {
+						reasoning_effort: {
+							type: "string",
+							description: providerRouteDefaults !== void 0 ? "Adapter-owned reasoning effort for the effective child route. Omit to use a compatible configured effort or the selected model's default." : "Adapter-owned reasoning effort for the effective child route. Omit to inherit a compatible configured/parent effort or use a newly selected model's default."
+						}
+					} : {}
+				},
+				output: {
+					schema: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
 								type: "string",
-								description: providerRouteDefaults !== void 0 ? "Model id interpreted by provider. Supply together with provider; omit both to use configured child defaults or this provider's route defaults." : "Model id interpreted by provider. Supply together with provider; omit both to use configured child defaults or inherit the parent route."
+								required: true,
+								const: "activation"
 							},
-							reasoning_effort: {
+							subagentId: {
 								type: "string",
-								description: providerRouteDefaults !== void 0 ? "Adapter-owned reasoning effort for the effective child route. Omit to use a compatible configured effort or the selected model's default." : "Adapter-owned reasoning effort for the effective child route. Omit to inherit a compatible configured/parent effort or use a newly selected model's default."
+								required: true
 							}
-						} : {},
-						...backgroundEnabled ? { run_in_background: {
-							type: "boolean",
-							description: continuable ? "Whether to run in the background and return a durable subagent id immediately. Defaults to true. Set false to wait for the result when your next action depends on it." : "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
-						} } : {}
+						}
 					},
-					output: {
-						schema: { oneOf: [
-							{
-								type: "object",
-								additionalProperties: false,
-								properties: {
-									kind: {
-										type: "string",
-										required: true,
-										const: "background"
-									},
-									jobId: {
-										type: "string",
-										required: true
-									}
-								}
-							},
-							{
-								type: "object",
-								additionalProperties: false,
-								properties: {
-									kind: {
-										type: "string",
-										required: true,
-										const: "continuable"
-									},
-									subagentId: {
-										type: "string",
-										required: true
-									}
-								}
-							},
-							{
-								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) => [{
+					render: (_args, value) => [{
+						type: "text",
+						text: `started subagent ${value.subagentId}`
+					}]
+				},
+				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 modelRequest = args;
+					const parentOptions = parentAgentOptionsForDelegation(parent);
+					const requiresRoutePreflight = hasDelegationModelRequest(modelRequest) || hasConfiguredLlmSelection(config.agentOptions);
+					const requestedChildAgentOptions = requestedAgentOptions(parentOptions, requiresRoutePreflight && providerRouteDefaults !== void 0 ? {
+						...providerRouteDefaults,
+						...config.agentOptions
+					} : config.agentOptions, modelRequest, modelSelectionEnabled);
+					assertAllowedModelSelection(modelSelectionPolicy, parentOptions, requestedChildAgentOptions, modelRequest);
+					if (requiresRoutePreflight) {
+						const llm = runtimeCtx.get("llm");
+						if (llm === void 0) throw new Error("cannot resolve the selected child LLM route because the `llm` service is unavailable");
+						await preflightChildLlmRoute(llm, parentOptions, requestedChildAgentOptions, exec.signal, providerRouteDefaults === void 0);
+						if (runtimeCtx.subagents.getProvider(config.provider) !== subagentProvider) throw new Error(`subagent provider "${config.provider}" changed while resolving the child LLM route; retry the delegation`);
+					}
+					exec.signal.throwIfAborted();
+					const maxDepth = runtimeCtx.subagents.resolveMaxDepth(config.maxDepth);
+					const request = {
+						...args.cwd === void 0 ? {} : { cwd: args.cwd },
+						prompt: [{
 							type: "text",
-							text: value.kind === "background" ? `started background subagent job ${value.jobId}` : value.kind === "continuable" ? `started subagent ${value.subagentId}` : 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 modelRequest = args;
-						const parentOptions = parentAgentOptionsForDelegation(parent);
-						const requiresRoutePreflight = hasDelegationModelRequest(modelRequest) || hasConfiguredLlmSelection(config.agentOptions);
-						const requestedChildAgentOptions = requestedAgentOptions(parentOptions, requiresRoutePreflight && providerRouteDefaults !== void 0 ? {
-							...providerRouteDefaults,
-							...config.agentOptions
-						} : config.agentOptions, modelRequest, modelSelectionEnabled);
-						assertAllowedModelSelection(modelSelectionPolicy, parentOptions, requestedChildAgentOptions, modelRequest);
-						if (requiresRoutePreflight) {
-							const llm = runtimeCtx.get("llm");
-							if (llm === void 0) throw new Error("cannot resolve the selected child LLM route because the `llm` service is unavailable");
-							await preflightChildLlmRoute(llm, parentOptions, requestedChildAgentOptions, exec.signal, providerRouteDefaults === void 0);
-							if (runtimeCtx.subagents.getProvider(config.provider) !== subagentProvider) throw new Error(`subagent provider "${config.provider}" changed while resolving the child LLM route; retry the delegation`);
-						}
-						exec.signal.throwIfAborted();
-						const maxDepth = runtimeCtx.subagents.resolveMaxDepth(config.maxDepth);
-						const request = {
+							text: args.prompt
+						}],
+						parent,
+						...requestedChildAgentOptions !== void 0 ? { agentOptions: requestedChildAgentOptions } : {},
+						...config.persona !== void 0 ? { persona: config.persona } : {},
+						...config.toolFilter !== void 0 ? { toolFilter: config.toolFilter } : {},
+						...maxDepth !== void 0 ? { maxDepth } : {}
+					};
+					return {
+						kind: "activation",
+						subagentId: (await runtimeCtx.subagents.startActivation({
+							provider: config.provider,
 							label: args.description,
-							prompt: [{
-								type: "text",
-								text: args.prompt
-							}],
-							parent,
-							...requestedChildAgentOptions !== void 0 ? { agentOptions: requestedChildAgentOptions } : {},
-							...config.persona !== void 0 ? { persona: config.persona } : {},
-							...config.toolFilter !== void 0 ? { toolFilter: config.toolFilter } : {},
-							...maxDepth !== void 0 ? { maxDepth } : {}
-						};
-						if (resolveDelegationRun(args, {
-							backgroundEnabled,
-							continuable
-						}).runInBackground) {
-							if (continuable) return {
-								kind: "continuable",
-								subagentId: (await runtimeCtx.subagents.startContinuable({
-									provider: config.provider,
-									label: args.description,
-									request,
-									signal: exec.signal
-								})).childId
-							};
-							const jobs = runtimeCtx.get("jobs");
-							if (jobs === void 0) throw new Error("background jobs unavailable: load @qilin-agent/jobs and @qilin-agent/tool-jobs");
-							return {
-								kind: "background",
-								jobId: jobs.start({
-									kind: "subagent",
-									label: args.description,
-									owner: parent.id,
-									run: () => {
-										const controller = new AbortController();
-										return {
-											cancel: (reason) => {
-												controller.abort(reason ?? "background subagent task killed");
-											},
-											done: settleStart(runtimeCtx.subagents.start(config.provider, {
-												...request,
-												signal: controller.signal
-											}), controller.signal)
-										};
-									}
-								})
-							};
-						}
-						return settleForegroundRun(await runtimeCtx.subagents.start(config.provider, {
-							...request,
-							signal: exec.signal
-						}));
-					}
-				}))
+							request,
+							signal: exec.signal,
+							delivery: "parent"
+						})).childId
+					};
+				}
+			});
+			mounted = {
+				subagentProvider,
+				disposeTool: runtimeCtx.effect(() => {
+					const unregister = runtimeCtx.tools.register(definition);
+					delegationTools.add(definition);
+					return () => {
+						delegationTools.delete(definition);
+						unregister();
+					};
+				})
 			};
 		};
 		runtimeCtx.on("subagent/provider-added", (subagentProvider) => {
@@ -573,10 +439,15 @@ function apply(ctx, config, session) {
 		const present = runtimeCtx.subagents.getProvider(config.provider);
 		if (present !== void 0) mount(present);
 		else runtimeCtx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? "subagent"}" tool will register when it appears`);
-		if (backgroundEnabled && continuable) runtimeCtx.systemPrompt.section({
+		runtimeCtx.systemPrompt.section({
 			name: `tool:${toolName}`,
 			order: runtimeCtx.systemPrompt.getSectionOrder("TOOL_SUBAGENT"),
-			text: (context) => mounted === void 0 || runtimeCtx.tools.get(toolName, context.scope) === void 0 ? "" : `Use ${toolName} in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set \`run_in_background: false\` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.`
+			text: (context) => {
+				if (mounted === void 0) return "";
+				const visible = [...delegationTools].filter((tool) => runtimeCtx.tools.get(tool.name, context.scope) === tool).map((tool) => tool.name).sort();
+				if (visible[0] !== toolName) return "";
+				return `Start independent delegations with ${visible.map((name) => `\`${name}\``).join(" or ")} together in one assistant message and continue useful work while they run.`;
+			}
 		});
 	};
 	if (config.modelSelectionSettings !== true) {

package/lib/model-selection-settings.js

@@ -37,58 +37,32 @@ function assertAllowedModelRoutes(routes) {
 }
 //#endregion
 //#region lib/types/model-selection-settings.js
-/** Host-owned opt-in setting for model-selectable subagent delegation. */
-/** User-settings section for model-selectable subagent delegation. */
-const SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE = "subagent-model-selection";
-/** Schema served to settings clients for the opt-in preference. */
-const SUBAGENT_MODEL_SELECTION_SETTINGS_SCHEMA = z.object({
-	enabled: z.boolean().default(false),
-	allowedModels: z.array(AllowedModelRouteSchema).default([])
-});
 /** Singleton settings owner read when delegation tools are composed for a Session. */
 var SubagentModelSelectionConfig = class extends Service {
+	config;
 	static Config = z.object({
-		enabled: z.boolean().default(false),
-		allowedModels: z.array(AllowedModelRouteSchema).default([])
+		enabled: z.boolean().default(false).volatile(),
+		allowedModels: z.array(AllowedModelRouteSchema).default([]).volatile()
 	});
-	source;
-	constructor(ctx, config = {}) {
+	constructor(ctx, config) {
 		super(ctx, "subagentModelSelection");
-		/* v8 ignore next */
-		const entry = {
-			enabled: config.enabled ?? false,
-			allowedModels: config.allowedModels ?? []
-		};
-		this.validate(entry);
-		this.source = () => entry;
-		ctx.inject(["settings"], (settingsCtx) => {
-			settingsCtx.settings.installSection(ctx, SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE, SUBAGENT_MODEL_SELECTION_SETTINGS_SCHEMA, entry, {
-				setSource: (source) => {
-					this.source = source;
-				},
-				validate: (value) => {
-					this.validate(value);
-				},
-				onChange: () => {}
-			});
-		});
+		this.config = config;
 	}
 	/**
 	* Read a detached selection preference for the next eligible Session composition.
 	* @returns the enabled state and exact allowed routes.
 	*/
 	current() {
-		const current = this.source();
+		const enabled = this.config.enabled.get();
+		const allowedModels = this.config.allowedModels.get();
+		assertAllowedModelRoutes(allowedModels);
+		if (enabled && allowedModels.length === 0) throw new Error("enabled subagent model selection requires at least one allowed model");
 		return {
-			enabled: current.enabled,
-			allowedModels: current.allowedModels.map((route) => ({ ...route }))
+			enabled,
+			allowedModels: allowedModels.map((route) => ({ ...route }))
 		};
 	}
-	validate(value) {
-		assertAllowedModelRoutes(value.allowedModels);
-		if (value.enabled && value.allowedModels.length === 0) throw new Error("enabled subagent model selection requires at least one allowed model");
-	}
 };
 const name = "subagent-model-selection-settings";
 //#endregion
-export { SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE, SUBAGENT_MODEL_SELECTION_SETTINGS_SCHEMA, SubagentModelSelectionConfig, SubagentModelSelectionConfig as default, name };
+export { SubagentModelSelectionConfig, SubagentModelSelectionConfig as default, name };

package/lib/types/index.d.ts

@@ -1,10 +1,8 @@
 /**
  * Model-facing delegation through one configured `ctx.subagents` provider.
  * Provider lifecycle controls tool registration and context-sensitive schema
- * wording. Foreground calls always dispose the run after collection.
- * Background policy is selected by this plugin's configuration: one-shot
- * calls own a plain Task, while continuable calls use
- * `ctx.subagents.startContinuable()`.
+ * wording. Every delegation starts a managed activation and returns its child
+ * id; the subagent runtime owns result delivery and resource cleanup.
  * @module @qilin-agent/tool-subagent
  */
 import type { Context } from '@qilin-agent/kylin';
@@ -27,18 +25,6 @@ export interface Config {
      * Session and inherit that decision in its child Sessions.
      */
     modelSelectionSettings?: boolean;
-    /**
-     * Expose `run_in_background` (default true). Disabled instances omit the
-     * parameter and reject forced background calls.
-     */
-    enableRunInBackground?: boolean;
-    /**
-     * Background execution policy (default `one-shot`). `one-shot` defaults calls
-     * to foreground; `continuable` defaults them to background, requires a provider
-     * with the `prepareContinuable` capability, and returns the durable child id.
-     * Follow-up adapters remain independently optional.
-     */
-    backgroundMode?: 'one-shot' | 'continuable';
     /**
      * Agent options applied to every child; omitted fields use child-loop defaults.
      */

package/lib/types/model-selection-settings.d.ts

@@ -1,4 +1,5 @@
 /** Host-owned opt-in setting for model-selectable subagent delegation. */
+import type { Volatile } from '@qilin-agent/kylin';
 import { Context, Service } from '@qilin-agent/kylin';
 import z from '@qilin-agent/schemastery';
 import { type AllowedModelRoute } from './model-selection.ts';
@@ -8,8 +9,6 @@ declare module '@qilin-agent/kylin' {
         subagentModelSelection: SubagentModelSelectionConfig;
     }
 }
-/** User-settings section for model-selectable subagent delegation. */
-export declare const SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE = "subagent-model-selection";
 /** Stored user preference; the shipped composition defaults it off. */
 export interface SubagentModelSelectionSettings {
     /** Whether newly composed top-level Sessions receive model selection. */
@@ -17,26 +16,29 @@ export interface SubagentModelSelectionSettings {
     /** Exact child LLM routes offered to newly composed top-level Sessions. */
     allowedModels: AllowedModelRoute[];
 }
-/** Schema served to settings clients for the opt-in preference. */
-export declare const SUBAGENT_MODEL_SELECTION_SETTINGS_SCHEMA: z<SubagentModelSelectionSettings>;
 /** Optional deployment base for the preference. */
 export interface Config {
     /** Initial enabled state inherited when the user document does not override it. */
-    enabled?: boolean;
+    enabled: Volatile<boolean>;
     /** Initial route list inherited when the user document does not override it. */
-    allowedModels?: AllowedModelRoute[];
+    allowedModels: Volatile<AllowedModelRoute[]>;
 }
 /** Singleton settings owner read when delegation tools are composed for a Session. */
 export declare class SubagentModelSelectionConfig extends Service {
-    static Config: z<Config>;
-    private source;
-    constructor(ctx: Context, config?: Config);
+    private config;
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "volatile-defined">;
+        allowedModels: z<NoInfer<AllowedModelRoute[]>, NoInfer<AllowedModelRoute[]>, "volatile-defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "volatile-defined">;
+        allowedModels: z<NoInfer<AllowedModelRoute[]>, NoInfer<AllowedModelRoute[]>, "volatile-defined">;
+    }>>, "plain">;
+    constructor(ctx: Context, config: Config);
     /**
      * Read a detached selection preference for the next eligible Session composition.
      * @returns the enabled state and exact allowed routes.
      */
     current(): SubagentModelSelectionSettings;
-    private validate;
 }
 export declare const name = "subagent-model-selection-settings";
 export default SubagentModelSelectionConfig;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/tool-subagent",
   "description": "Model-facing subagent delegation tool over the ctx.subagents seam",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "publishConfig": {
     "access": "public"
   },
@@ -35,17 +35,17 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/agent": "3.1.3",
-    "@qilin-agent/session": "3.1.3",
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/session-projection": "3.1.3",
-    "@qilin-agent/settings": "3.1.3",
-    "@qilin-agent/scope": "3.1.3",
-    "@qilin-agent/subagent": "3.1.3",
-    "@qilin-agent/jobs": "3.1.3",
-    "@qilin-agent/tools": "3.1.3",
+    "@qilin-agent/agent": "3.1.5",
+    "@qilin-agent/llm": "3.1.5",
+    "@qilin-agent/session": "3.1.5",
+    "@qilin-agent/session-projection": "3.1.5",
+    "@qilin-agent/settings": "3.1.5",
+    "@qilin-agent/subagent": "3.1.5",
+    "@qilin-agent/system-prompt": "3.1.5",
+    "@qilin-agent/scope": "3.1.5",
     "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/system-prompt": "3.1.3"
+    "@qilin-agent/tools": "3.1.5",
+    "@qilin-agent/jobs": "3.1.5"
   },
   "dependencies": {
     "zod": "^4.4.3",
@@ -53,21 +53,21 @@
   },
   "devDependencies": {
     "@qilin-agent/kylin-plugin-loader": "~1.0.4",
-    "@qilin-agent/agent": "3.1.3",
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/session": "3.1.3",
-    "@qilin-agent/scope": "3.1.3",
-    "@qilin-agent/session-persistence": "3.1.3",
-    "@qilin-agent/settings": "3.1.3",
-    "@qilin-agent/session-persistence-jsonl": "3.1.3",
-    "@qilin-agent/subagent-spawn-in-process": "3.1.3",
-    "@qilin-agent/jobs": "3.1.3",
-    "@qilin-agent/system-prompt": "3.1.3",
-    "@qilin-agent/subagent": "3.1.3",
-    "@qilin-agent/jobs-local": "3.1.3",
-    "@qilin-agent/tools": "3.1.3",
+    "@qilin-agent/llm": "3.1.5",
+    "@qilin-agent/session": "3.1.5",
+    "@qilin-agent/scope": "3.1.5",
+    "@qilin-agent/agent": "3.1.5",
+    "@qilin-agent/session-persistence-jsonl": "3.1.5",
+    "@qilin-agent/settings": "3.1.5",
+    "@qilin-agent/system-prompt": "3.1.5",
+    "@qilin-agent/session-persistence": "3.1.5",
+    "@qilin-agent/subagent-spawn-in-process": "3.1.5",
+    "@qilin-agent/tool-jobs": "3.1.5",
+    "@qilin-agent/jobs-local": "3.1.5",
+    "@qilin-agent/subagent": "3.1.5",
+    "@qilin-agent/jobs": "3.1.5",
+    "@qilin-agent/tools": "3.1.5",
     "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/session-projection": "3.1.3",
-    "@qilin-agent/tool-jobs": "3.1.3"
+    "@qilin-agent/session-projection": "3.1.5"
   }
 }