/** * 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()`. * @module @deepseek-ai/dsh-tool-subagent */ import type { Context } from '@deepseek-ai/cordis' import z from '@deepseek-ai/schemastery' import { scopeChainOf, scopeOf } from '@deepseek-ai/dsh-scope' import { defineTool } from '@deepseek-ai/dsh-tools' import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent' import { ReasoningEffortId } from '@deepseek-ai/dsh-llm' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import type { JsonValue } from '@deepseek-ai/dsh-util-values' import { SessionSeq } from '@deepseek-ai/dsh-session' import type { Session } from '@deepseek-ai/dsh-session' import { assertSubagentMaxDepth, parentAgentOptionsForDelegation, settleRun, } from '@deepseek-ai/dsh-subagent' import type { SubagentProvider, SubagentResult, SubagentRun } from '@deepseek-ai/dsh-subagent' import type { JobOutcome } from '@deepseek-ai/dsh-jobs' import { assertAllowedModelSelection, hasConfiguredLlmSelection, hasDelegationModelRequest, preflightChildLlmRoute, requestedAgentOptions, } from './model-selection.ts' import type { DelegationModelRequest, ModelSelectionPolicy } from './model-selection.ts' import { registerListSubagentModels } from './list-models.ts' import type {} from './model-selection-settings.ts' import { recordSubagentModelSelection, subagentModelSelectionProjectionDefinition, subagentModelSelectionPolicy, } from './model-selection-state.ts' export const name = 'tool-subagent' export const inject = ['tools', 'subagents', 'systemPrompt', 'sessionProjections'] /** Config: which registered provider this tool delegates to, plus child defaults. */ export interface Config { /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */ provider: string /** * Model-facing tool name (default `subagent`). Each loaded instance must use * a distinct name. */ toolName?: string /** * Sample the Host `subagent-model-selection` setting for each new top-level * 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. */ agentOptions?: AgentOptions /** * Per-child persona that shadows `deployment:persona-prefix`. Requires the * provider's `persona` capability; omission preserves the deployment persona. */ persona?: string /** * Tool filter applied to every child. Filtered tools disappear from its * prompt and reject execution. Requires the provider's `toolFilter` * capability; unknown names fail startup. */ toolFilter?: { /** Global tool names the child keeps; everything else is removed. */ allow?: string[] /** Global tool names removed from the child. */ deny?: string[] } /** * Maximum child depth: a non-negative safe integer (`0` forbids delegation), * or `'provider-managed'` to send no cap. A numeric cap * requires the provider's `depthLimit` capability (mount fails loud * otherwise). The provider checks the calling agent's current depth at every * start; the tool remains model-visible so runtime policy owns rejection. * `'provider-managed'` is for an out-of-process provider whose recursion * budget belongs to the child runtime or its own deployment. Omission reads * the current Host subagent depth setting (default `1`) at each delegation. */ maxDepth?: number | 'provider-managed' } export const Config: z = 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'] as const).default('one-shot'), // Prevent Schemastery from materializing omitted agentOptions as `{}`. agentOptions: z.object({ provider: z.string(), model: z.string(), reasoningEffort: z.string().min(1) as z>, maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER), }).default(undefined as unknown as { provider: string model: string reasoningEffort: ReturnType maxTokens: number }), persona: z.string(), // Preserve omission; Schemastery's `{ allow: [] }` default would deny every tool. toolFilter: z.object({ allow: z.array(z.string()).default(undefined as unknown as string[]), deny: z.array(z.string()).default(undefined as unknown as string[]), }).default(undefined as unknown as { allow: string[]; deny: string[] }), maxDepth: z.union([z.natural().max(Number.MAX_SAFE_INTEGER), z.const('provider-managed' as const)]), }) /** Render text blocks from the canonical JSON block array without trusting arbitrary values. */ function outputValueText(values: JsonValue[]): string { return values .filter((value): value is { type: 'text'; text: string } => 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: Promise, signal: AbortSignal): Promise { try { return await settleRun(await start) } catch (error: unknown) { // Product providers aggregate startup and rollback failures. Cancellation // must not turn a failed cleanup into a cleanly killed Job. 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: SubagentResult): string | undefined { switch (result.stopReason) { case 'completed': return undefined 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' // Merge-extensible union: a backend may add stop reasons. Treat an unknown // terminal reason as a failure rather than reporting partial output as success. 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: string, result: SubagentResult): string { const diagnostic = result.diagnostic === undefined ? '' : `\nDiagnostic: ${result.diagnostic}` const text = result.output .filter((block): block is Extract => block.type === 'text') .map(block => block.text) .join('') const partial = text.length === 0 ? '' : `\nPartial output before the run ended:\n${text}` return `${error}${diagnostic}${partial}` } type ForegroundToolResult = { readonly kind: 'foreground' readonly runId: SubagentRun['id'] readonly output: JsonValue[] } /** * Collect and release one foreground run without letting disposal replace an * independent result failure. */ async function settleForegroundRun(run: SubagentRun): Promise { const [execution] = await Promise.allSettled([ run.result.then((result): ForegroundToolResult => { const error = stopReasonError(result) if (error !== undefined) { // The registry converts this throw to isError; partial output is not // success, but the preserved partial answer still reaches the parent. throw new Error(withDiagnosticAndPartialText(error, result)) } return { kind: 'foreground', runId: run.id, // Content blocks already cross durable JSON boundaries elsewhere; // the registry performs the authoritative lossless snapshot here. output: result.output as unknown as JsonValue[], } }), ]) 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}). * A fresh child needs a standalone prompt; a forked child already sees the * conversation's completed turns — telling the model to restate everything * (or, worse, that the child "does not see this conversation") would be false * for a fork. * @param inheritsConversation - whether the child's conversation is seeded * with the parent's completed turns; this says nothing about tool, service, * scope, or authority inheritance. * @returns the tool `description` and the `prompt` parameter description. */ function providerWording(inheritsConversation: boolean): { description: string; promptDescription: string } { if (inheritsConversation) { return { description: 'Delegate a task to a subagent that inherits this conversation: a child agent seeded with all ' + 'completed turns so far (it does not see the current in-flight turn). Use this when the subtask ' + 'builds on this conversation\'s context — a follow-up analysis, ' + 'a review, a continuation — without consuming this conversation\'s context for the work itself. ' + 'You receive its result, not its intermediate steps.', 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.', promptDescription: 'The complete, self-contained task for the subagent. It does not share this ' + 'conversation\'s context, so include everything it needs.', } } interface DelegationRunRequest { readonly run_in_background?: boolean } interface DelegationRunSpec { readonly runInBackground: boolean } /** Resolve the model's optional scheduling request into one execution route. */ function resolveDelegationRun( request: DelegationRunRequest, options: { readonly backgroundEnabled: boolean; readonly continuable: boolean }, ): DelegationRunSpec { if (!options.backgroundEnabled) { // The validator permits undeclared keys, so schema omission also needs // execution-time enforcement. if (request.run_in_background === true) { throw new Error('run_in_background is disabled for this tool instance (enableRunInBackground: false)') } return { runInBackground: false } } return { // Continuable work is independently scheduled unless the caller explicitly // needs the result before its next action. One-shot policy keeps its existing // foreground default because its background result requires Task collection. runInBackground: request.run_in_background ?? options.continuable, } } /** * Install one delegation-tool composition. * @param ctx - Context that owns the registrations. * @param config - delegation-tool configuration. * @param session - unpublished Session supplied by a direct Agent setup; omit for a standing composition. */ export function apply(ctx: Context, config: Config, session?: Session): void { // Direct apply() bypasses Schemastery's numeric constraints. A direct-apply // omission stays capless (the schema default only runs through the loader). if (config.maxDepth !== 'provider-managed') assertSubagentMaxDepth(config.maxDepth) // Reject an empty explicit filter at load instead of failing every delegation. if (config.toolFilter !== undefined && config.toolFilter.allow === undefined && config.toolFilter.deny === undefined) { 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) const assertSubagentProviderConfiguration = (subagentProvider: SubagentProvider): void => { if (ctx.subagents.resolveMaxDepth(config.maxDepth) !== undefined && !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 !== undefined && !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 === undefined) { throw new Error( `tool-subagent: provider "${subagentProvider.name}" does not support \`backgroundMode: continuable\``, ) } } // Validate provider-owned config outside the optional LLM binding so an // invalid provider always rejects its registration or this plugin's load. ctx.on('subagent/provider-added', (subagentProvider) => { if (subagentProvider.name === config.provider) assertSubagentProviderConfiguration(subagentProvider) }) const initialProvider = ctx.subagents.getProvider(config.provider) if (initialProvider !== undefined) assertSubagentProviderConfiguration(initialProvider) const install = (runtimeCtx: Context, modelSelectionPolicy: ModelSelectionPolicy | undefined): void => { const modelSelectionEnabled = modelSelectionPolicy !== undefined if (modelSelectionPolicy !== undefined) registerListSubagentModels(runtimeCtx, modelSelectionPolicy) // Load order and HMR replacement can change provider availability while // this fiber remains active. let mounted: { subagentProvider: SubagentProvider; disposeTool: () => void } | undefined const mount = (subagentProvider: SubagentProvider): void => { assertSubagentProviderConfiguration(subagentProvider) const wording = providerWording(subagentProvider.inheritsParentContext) const providerRouteDefaults = subagentProvider.agentRouteDefaults const selectionDescription = providerRouteDefaults !== undefined ? ' 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.' const choiceDescription = !modelSelectionEnabled ? '' : selectionDescription + (subagentProvider.inheritsParentContext ? ' Changing the route can prevent provider-side reuse of the inherited conversation prefix.' : '') const disposeTool = runtimeCtx.tools.register(defineTool({ name: toolName, description: wording.description + (backgroundEnabled // The completion notice is the continuation service's own behavior, not // a separately installed capability, so this promise holds whenever the // continuable background path is reachable at all. ? 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: { 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' as const, description: providerRouteDefaults !== undefined ? '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: { type: 'string' as const, description: providerRouteDefaults !== undefined ? '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.', }, reasoning_effort: { type: 'string' as const, description: providerRouteDefaults !== undefined ? '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.', }, } : {}, ...backgroundEnabled ? { run_in_background: { type: 'boolean' as const, 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) => [{ type: 'text', text: value.kind === 'background' ? `started background subagent job ${value.jobId}` : value.kind === 'continuable' ? `started subagent ${value.subagentId}` : outputValueText(value.output), }], }, // Children never mutate the parent session; the one parent-owned write // (tasks.start) is a synchronous commutative insertion. isConcurrencySafe: () => true, async execute(args, exec) { const parent = exec.agent if (!parent) { // Non-agent callers provide no parent for delegation ownership. throw new Error('subagent tool requires a calling agent (exec.agent was undefined)') } const modelRequest = args as DelegationModelRequest const parentOptions = parentAgentOptionsForDelegation(parent) const requiresRoutePreflight = hasDelegationModelRequest(modelRequest) || hasConfiguredLlmSelection(config.agentOptions) const configuredChildAgentOptions = requiresRoutePreflight && providerRouteDefaults !== undefined ? { ...providerRouteDefaults, ...config.agentOptions } : config.agentOptions const requestedChildAgentOptions = requestedAgentOptions( parentOptions, configuredChildAgentOptions, modelRequest, modelSelectionEnabled, ) assertAllowedModelSelection( modelSelectionPolicy, parentOptions, requestedChildAgentOptions, modelRequest, ) if (requiresRoutePreflight) { const llm = runtimeCtx.get('llm') if (llm === undefined) { throw new Error('cannot resolve the selected child LLM route because the `llm` service is unavailable') } await preflightChildLlmRoute( llm, parentOptions, requestedChildAgentOptions, exec.signal, providerRouteDefaults === undefined, ) 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 = { label: args.description, prompt: [{ type: 'text', text: args.prompt }] as ContentBlock[], parent, ...requestedChildAgentOptions !== undefined ? { agentOptions: requestedChildAgentOptions } : {}, ...config.persona !== undefined ? { persona: config.persona } : {}, ...config.toolFilter !== undefined ? { toolFilter: config.toolFilter } : {}, ...maxDepth !== undefined ? { maxDepth } : {}, } const runSpec = resolveDelegationRun(args, { backgroundEnabled, continuable }) if (runSpec.runInBackground) { if (continuable) { // Resolves at inbox acceptance: the child owns its own turns from // there, so this call neither waits for nor collects a result. const started = await runtimeCtx.subagents.startContinuable({ provider: config.provider, label: args.description, request, signal: exec.signal, }) return { kind: 'continuable' as const, subagentId: started.childId } } const jobs = runtimeCtx.get('jobs') if (jobs === undefined) { throw new Error('background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs') } // One-shot background child: job preflight finishes before the // starter can spawn, and the task-owned signal covers startup. const id = jobs.start({ kind: 'subagent', label: args.description, owner: parent, run: () => { const controller = new AbortController() const start = runtimeCtx.subagents.start(config.provider, { ...request, signal: controller.signal }) return { cancel: (reason?: string) => { controller.abort(reason ?? 'background subagent task killed') }, done: settleStart(start, controller.signal), // No readOutput: the child session owns intermediate detail. } }, }) return { kind: 'background' as const, jobId: id } } const run: SubagentRun = await runtimeCtx.subagents.start(config.provider, { ...request, signal: exec.signal, }) return settleForegroundRun(run) }, })) mounted = { subagentProvider, disposeTool } } // Register listeners before checking presence so no synchronous change is missed. // TODO(subagent-dup-toolname): two waiting one-shot fibers configured with the // same toolName collide when their provider appears, and the duplicate-name // throw rolls back the provider registration. Continuable instances reserve // their prompt-section name during apply() and fail earlier. Add an intent // registry if the late one-shot collision occurs in a shipped composition. runtimeCtx.on('subagent/provider-added', (subagentProvider) => { if (subagentProvider.name === config.provider && mounted === undefined) mount(subagentProvider) }) runtimeCtx.on('subagent/provider-removed', (name) => { if (name !== config.provider || mounted === undefined) return mounted.disposeTool() mounted = undefined }) const present = runtimeCtx.subagents.getProvider(config.provider) if (present !== undefined) { mount(present) } else { // A backend fiber may activate later; a misspelled provider remains visible in this log. runtimeCtx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? 'subagent'}" tool will register when it appears`) } if (backgroundEnabled && continuable) { // The section follows provider availability without its own manual // lifecycle: empty text is omitted from rendered prompts while the tool is // absent, and the registration itself stays owned by this plugin fiber. runtimeCtx.systemPrompt.section({ name: `tool:${toolName}`, order: runtimeCtx.systemPrompt.getSectionOrder('TOOL_SUBAGENT'), text: context => mounted === undefined || runtimeCtx.tools.get(toolName, context.scope) === undefined ? '' : `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.`, }) } } if (config.modelSelectionSettings !== true) { install(ctx, undefined) return } const settings = ctx.get('subagentModelSelection') if (settings === undefined) { throw new Error( 'tool-subagent: `modelSelectionSettings` requires ' + '@deepseek-ai/dsh-tool-subagent/model-selection-settings in the Host scope', ) } const selectForSession = (target: Session): ModelSelectionPolicy | undefined => { const freshSession = target.firstLiveSeq === 0 // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred. && target.eventAt(SessionSeq(0))?.type !== 'session/end-seed' let allowedModels = subagentModelSelectionPolicy(ctx.sessionProjections, target) if (allowedModels === undefined) { const parentId = target.header.origin === 'subagent' ? target.header.parentSession : undefined if (parentId !== undefined) { const sessions = ctx.get('sessions') if (sessions === undefined) { throw new Error('tool-subagent: child model-selection inheritance requires the Session registry') } const parent = sessions.get(parentId) allowedModels = parent === undefined ? undefined : subagentModelSelectionPolicy(ctx.sessionProjections, parent) } else if (freshSession) { const current = settings.current() allowedModels = current.enabled ? current.allowedModels : undefined } } if (allowedModels !== undefined) { recordSubagentModelSelection(ctx.sessionProjections, target, allowedModels) } return allowedModels === undefined ? undefined : { routes: allowedModels } } if (session !== undefined) { install(ctx, selectForSession(session)) return } const compositionScope = scopeOf(ctx) if (compositionScope === undefined) { throw new Error('tool-subagent: standing `modelSelectionSettings` requires a scoped preset Context') } const agents = ctx.get('agents') /* v8 ignore next -- shipped preset compositions always include the Agent registry. */ if (agents === undefined) throw new Error('tool-subagent: standing `modelSelectionSettings` requires the Agent registry') const scopedInstalls = new WeakMap>() const installing = new WeakSet() const belongsToComposition = (candidate: Agent): boolean => scopeChainOf(scopeOf(candidate.ctx)).includes(compositionScope) const installScoped = (candidate: Agent): ReturnType | undefined => { const existing = scopedInstalls.get(candidate) if (existing !== undefined) return existing if (installing.has(candidate)) return // Reserve before the injected fiber runs: tool registration emits // `tools/change` synchronously, which re-enters the reconciliation below. installing.add(candidate) let fiber: ReturnType try { const policy = selectForSession(candidate.session) fiber = candidate.ctx.inject(['tools', 'subagents', 'systemPrompt'], (runtimeCtx) => { install(runtimeCtx, policy) }) } finally { installing.delete(candidate) } scopedInstalls.set(candidate, fiber) return fiber } const removeScoped = (candidate: Agent): void => { const fiber = scopedInstalls.get(candidate) if (fiber === undefined) return scopedInstalls.delete(candidate) /* v8 ignore next 3 -- Cordis Fiber disposal contains registration cleanup failures; this is the final diagnostic sink. */ void fiber.dispose().catch((error: unknown) => { ctx.logger.warn(`tool-subagent: failed to remove recomposed Agent "${candidate.id}" definitions: ${String(error)}`) }) } const reconcileComposedAgents = (): void => { for (const candidate of agents.list()) { if (belongsToComposition(candidate)) installScoped(candidate) else removeScoped(candidate) } } // The preset-scoped listener admits descendant Agents and installs the // sampled tool definition in each Agent's own scope, so a later settings // change cannot mutate a live session. ctx.on('agent/created', async ({ agent: created }) => { await installScoped(created) }) ctx.on('agent/disposed', ({ agent: disposed }) => { removeScoped(disposed) }) // Reparenting an Agent between standing presets changes its inherited tool // set and emits `tools/change`; reconcile the Agent-owned override with the // new ancestry. Other registry changes are idempotent no-ops here. ctx.on('tools/change', reconcileComposedAgents) reconcileComposedAgents() }