dsh-agent-plugins-market 0.6.2 → 0.7.1

package/lib/routes.js

@@ -130,7 +130,7 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         }
     });
     post(MARKET_ROUTES.addSource, async (body) => {
-        const url = String(body['url'] ?? '').trim();
+        const url = textField(body['url'] ?? '', 'source url').trim();
         if (url === '')
             throw new Error('missing source url');
         const local = body['local'] === true;
@@ -145,11 +145,11 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             if (!url.startsWith('~/') && url !== '~' && !isAbsolute(expanded))
                 throw new Error('local source url must be an absolute path or start with ~/');
         }
-        const branch = body['branch'];
+        const branch = body['branch'] === undefined ? undefined : textField(body['branch'], 'branch');
         const sha256 = parseSha256(body['sha256']);
         const source = await manager.addSource({
             url: local || kind === 'local' ? expandHome(url) : url,
-            ...(typeof branch === 'string' && branch.trim() !== '' ? { branch: branch.trim() } : {}),
+            ...(branch !== undefined && branch.trim() !== '' ? { branch: branch.trim() } : {}),
             ...(local ? { local: true } : {}),
             ...(kind === undefined ? {} : { kind }),
             ...(sha256 === undefined ? {} : { sha256 })
@@ -162,13 +162,13 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             throw new Error('missing source id');
         const patch = {};
         if (body['url'] !== undefined) {
-            const url = String(body['url']).trim();
+            const url = textField(body['url'], 'source url').trim();
             if (url === '')
                 throw new Error('missing source url');
             patch.url = url;
         }
         if (body['branch'] !== undefined)
-            patch.branch = String(body['branch']).trim();
+            patch.branch = textField(body['branch'], 'branch').trim();
         if (body['local'] !== undefined)
             patch.local = body['local'] === true;
         const kind = parseSourceKind(body['kind']);
@@ -197,8 +197,8 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         return {};
     });
     post(MARKET_ROUTES.refreshSource, async (body) => {
-        const id = body['id'];
-        await manager.refreshSource(typeof id === 'string' && id !== '' ? id : undefined);
+        const id = body['id'] === undefined ? undefined : textField(body['id'], 'source id');
+        await manager.refreshSource(id === '' ? undefined : id);
         return {};
     });
     post(MARKET_ROUTES.install, async (body) => {
@@ -257,6 +257,18 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         await manager.setMcpOverride(sourceId, suiteId, serverKey, sanitized ?? null);
         return {};
     });
+    // Enable or disable one declared MCP server. Addressed by the same
+    // source-qualified suite id the status rows carry, so the card can toggle a
+    // server without holding the source and suite ids apart.
+    post(MARKET_ROUTES.setMcpServerEnabled, async (body) => {
+        const suiteKey = textField(body['suiteId'] ?? '', 'MCP suite id');
+        const serverKey = textField(body['serverKey'] ?? '', 'MCP server key');
+        const enabled = body['enabled'];
+        if (typeof enabled !== 'boolean')
+            throw new Error('missing boolean enabled');
+        await manager.setMcpServerEnabled(suiteKey, serverKey, enabled);
+        return {};
+    });
     // Manual MCP reconcile: retries failed mounts and clears residual tools
     // without touching any catalog state.
     post(MARKET_ROUTES.mcpRetry, async () => {
@@ -299,12 +311,24 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         return {};
     });
     post(`${MARKET_ROUTES.lspServers}/enabled`, async (body) => {
-        const id = String(body['id'] ?? '');
+        const id = textField(body['id'] ?? '', 'LSP server id');
         if (id === '')
             throw new Error('missing LSP server id');
-        await manager.setLspServerEnabled(id, body['enabled'] !== false);
+        const enabled = body['enabled'];
+        if (typeof enabled !== 'boolean')
+            throw new Error('missing boolean enabled');
+        await manager.setLspServerEnabled(id, enabled);
         return {};
     });
+    // Upgrade repair: drop the hand-written profile layer an older release told
+    // the user to add for LSP. It edits a file the user owns, so the profile
+    // name is matched against what is on disk and nothing else is touched.
+    post(MARKET_ROUTES.migrateLspSeam, async (body) => {
+        const profile = textField(body['profile'] ?? '', 'profile name').trim();
+        if (profile === '')
+            throw new Error('missing profile name');
+        return { migration: await manager.migrateLegacyLspSeam(profile) };
+    });
     // User panel CRUD (skills / commands / agent personas). The host web
     // server matches exact pathnames, so the entry name rides the `name` query
     // parameter (GET read, POST replace, POST .../delete remove). The routes
@@ -327,8 +351,8 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
                 sendJson(response, 200, { entry });
             });
             post(`${userPanelRoute(kind)}/create`, async (body) => {
-                const name = String(body['name'] ?? '').trim();
-                const text = String(body['text'] ?? '');
+                const name = textField(body['name'] ?? '', 'entry name').trim();
+                const text = textField(body['text'] ?? '', 'entry text');
                 if (name === '')
                     throw new Error('missing entry name');
                 const entry = await storeOf(kind).create(name, text);
@@ -337,7 +361,7 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             });
             post(`${userPanelRoute(kind)}/update`, async (body, request) => {
                 const name = queryOf(request).get('name') ?? '';
-                const text = String(body['text'] ?? '');
+                const text = textField(body['text'] ?? '', 'entry text');
                 if (name === '')
                     throw new Error('missing entry name');
                 await storeOf(kind).update(name, text);
@@ -345,7 +369,7 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
                 return {};
             });
             post(`${userPanelRoute(kind)}/delete`, async (body) => {
-                const name = String(body['name'] ?? '');
+                const name = textField(body['name'] ?? '', 'entry name');
                 if (name === '')
                     throw new Error('missing entry name');
                 await storeOf(kind).remove(name);
@@ -359,6 +383,23 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             dispose();
     };
 }
+/**
+ * Read a request field this route documents as a string. Bodies are arbitrary
+ * JSON, so the field may arrive as any value; anything but a string is
+ * rejected rather than coerced, because `String({})` is `"[object Object]"` —
+ * a non-empty value that every check downstream would accept and store as a
+ * source url, a branch name, or an entry name. Empty stays empty so each
+ * caller keeps owning whether that means "missing".
+ */
+function textField(value, label) {
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be a string`);
+    return value;
+}
+/** Render an untrusted field for a diagnostic message. Never a value reader — see `textField`. */
+function describe(value) {
+    return String(value);
+}
 function parseTarget(body) {
     const sourceId = body['sourceId'];
     const suiteId = body['suiteId'];
@@ -374,13 +415,13 @@ function parseSourceKind(raw) {
         return undefined;
     if (raw === 'git' || raw === 'local' || raw === 'archive')
         return raw;
-    throw new Error(`invalid source kind "${String(raw)}"`);
+    throw new Error(`invalid source kind "${describe(raw)}"`);
 }
 /** Parse an optional SHA-256 hex digest; rejects malformed values. */
 function parseSha256(raw) {
     if (raw === undefined || raw === null || raw === '')
         return undefined;
-    const value = String(raw).trim().toLowerCase();
+    const value = textField(raw, 'sha256').trim().toLowerCase();
     if (!/^[0-9a-f]{64}$/.test(value))
         throw new Error('sha256 must be a 64-character hex digest');
     return value;
@@ -396,6 +437,7 @@ function sameOrigin(request) {
         return false;
     }
 }
+/** Parses the request body; `undefined` for an oversized, unparsable, or failed read. */
 function readJsonBody(request) {
     return new Promise(resolve => {
         let size = 0;

package/lib/runtime/agent-role-names.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+/**
+ * The `[source, suite, kind, name]` identity the host encodes into a discovery
+ * name, or `undefined` for a name that is not one — a user-authored role name
+ * is a plain string, and anything else carries no identity.
+ */
+function roleIdentity(name) {
+    let parsed;
+    try {
+        parsed = JSON.parse(name);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed))
+        return undefined;
+    const parts = parsed;
+    if (parts.length !== 4)
+        return undefined;
+    const [source, suite, kind, id] = parts;
+    if (typeof source !== 'string' || typeof suite !== 'string' || typeof kind !== 'string' || typeof id !== 'string')
+        return undefined;
+    return [source, suite, kind, id];
+}
+/** Internal IDs stay opaque to callers; only colliding resource names need qualification. */
+export function namedAgentRoles(entries) {
+    const roles = entries.map(entry => {
+        const identity = roleIdentity(entry.name);
+        const base = identity === undefined ? entry.name : identity[3].replace(/\.agent$/, '');
+        return { entry, base, suite: identity?.[1] ?? 'user', source: identity?.[0] ?? 'user', level: 0 };
+    });
+    const baseCounts = new Map();
+    for (const role of roles)
+        baseCounts.set(role.base, (baseCounts.get(role.base) ?? 0) + 1);
+    for (const role of roles)
+        if ((baseCounts.get(role.base) ?? 0) > 1)
+            role.level = 1;
+    const candidate = (role) => {
+        if (role.level === 0)
+            return role.base;
+        const qualified = `${role.suite}/${role.base}`;
+        const fullyQualified = `${role.source}/${role.suite}/${role.base}`;
+        if (role.level === 1)
+            return qualified;
+        if (role.level === 2)
+            return fullyQualified;
+        return `${fullyQualified}~${createHash('sha256').update(role.entry.name).digest('hex')}`;
+    };
+    // Recheck all names: a qualified collision may overlap another role's literal name.
+    for (;;) {
+        const groups = new Map();
+        for (const role of roles) {
+            const key = candidate(role);
+            groups.set(key, [...(groups.get(key) ?? []), role]);
+        }
+        let changed = false;
+        for (const group of groups.values()) {
+            if (group.length < 2)
+                continue;
+            for (const role of group) {
+                if (role.level < 3) {
+                    role.level++;
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            return roles.map(role => ({ ...role.entry, callName: candidate(role) }));
+    }
+}

package/lib/runtime/agent-role-router.js

@@ -4,7 +4,14 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { parse as parseYaml } from 'yaml';
 import { mountSubagentCatalog } from './subagent-catalog.js';
 import { bindHostLocale } from './host-locale.js';
-export const AGENT_ROLE_TOOL_NAME = 'subagents_run';
+import { namedAgentRoles } from './agent-role-names.js';
+import { expandPluginPaths } from '../catalog/plugin-variables.js';
+export const AGENT_ROLE_TOOL_NAME = 'subagent_run';
+/**
+ * Absolute delegation-depth cap applied to every role child. The host default is
+ * the same value; keeping it explicit preserves the shipped recursion budget.
+ */
+const MAX_AGENT_ROLE_DEPTH = 3;
 function optionalText(value, key) {
     if (value === undefined)
         return undefined;
@@ -12,19 +19,7 @@ function optionalText(value, key) {
         throw new Error(`agent metadata ${key} must be a non-empty string`);
     return value.trim();
 }
-function toolList(value, key) {
-    if (value === undefined)
-        return undefined;
-    const entries = typeof value === 'string' ? value.split(',') : Array.isArray(value) ? value : [value];
-    return [
-        ...new Set(entries.map(entry => {
-            if (typeof entry !== 'string' || !/^[\w.:-]+$/.test(entry.trim()))
-                throw new Error(`agent metadata ${key} must contain tool names (comma-separated or a YAML array)`);
-            return entry.trim();
-        }))
-    ];
-}
-/** Strict YAML parsing prevents malformed routing/restriction metadata from silently inheriting wider privileges. */
+/** Strict YAML parsing prevents malformed routing metadata from silently inheriting wider privileges. */
 export function parseAgentRole(text) {
     const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
     if (match === null) {
@@ -32,7 +27,11 @@ export function parseAgentRole(text) {
             throw new Error('agent frontmatter is not closed');
         return { content: text, disabled: false };
     }
-    const parsed = parseYaml(match[1]);
+    // A matched block always carries its body; the check keeps the type honest.
+    const frontmatter = match[1];
+    if (frontmatter === undefined)
+        throw new Error('agent frontmatter is not closed');
+    const parsed = parseYaml(frontmatter);
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
         throw new Error('agent frontmatter must be a YAML object');
     const metadata = parsed;
@@ -56,51 +55,71 @@ export function parseAgentRole(text) {
         ...(provider === undefined ? {} : { provider }),
         ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
         ...(title === undefined ? {} : { title }),
-        ...(description === undefined ? {} : { description }),
-        ...(metadata.tools === undefined ? {} : { tools: toolList(metadata.tools, 'tools') }),
-        ...(metadata.disallowedTools === undefined ? {} : { disallowedTools: toolList(metadata.disallowedTools, 'disallowedTools') })
+        ...(description === undefined ? {} : { description })
     };
 }
-/** Bare ids must resolve uniquely; Claude aliases are accepted only if actually advertised by a DSH provider. */
-export async function resolveAgentModel(policy, catalog) {
-    if (policy.model === undefined)
-        return policy.provider === undefined ? {} : { provider: policy.provider };
-    const providers = catalog.listProviders();
-    if (policy.provider !== undefined) {
-        if (!providers.some(provider => provider.id === policy.provider))
-            throw new Error(`agent model provider "${policy.provider}" is not registered`);
-        return { provider: policy.provider, model: policy.model };
+function parentRouteOf(parent) {
+    const agent = parent;
+    return agent?.session?.requestHeader?.()?.config ?? agent?.options ?? {};
+}
+/**
+ * Resolve the child LLM options one card may contribute.
+ *
+ * A card route is advisory. Only an exact `provider` plus `model` pair is
+ * applied, and only when the live LLM runtime accepts it; every other
+ * declaration — a bare id, a Claude alias, a lone `provider`, an unsupported
+ * effort — degrades to inheriting the parent route and reports a diagnostic.
+ * @param policy - the card's parsed routing metadata.
+ * @param parent - the calling Agent whose route an unusable declaration falls back to.
+ * @param llm - live LLM runtime owning provider, model and effort validation.
+ * @param signal - tool-call cancellation signal.
+ * @param subject - role name used in diagnostics.
+ * @param diagnose - diagnostic sink; degradation is reported, never silent.
+ * @returns the options to send, or undefined for pure inheritance.
+ */
+export async function resolveAgentOptions(policy, parent, llm, signal, subject, diagnose) {
+    // One value, so a half-specified route can never be forwarded downstream.
+    const requested = policy.provider === undefined || policy.model === undefined ? undefined : { provider: policy.provider, model: policy.model };
+    if (requested === undefined && (policy.provider !== undefined || policy.model !== undefined)) {
+        const declared = [policy.provider, policy.model].filter(value => value !== undefined).join('/');
+        diagnose(`agent "${subject}": route "${declared}" needs an exact provider and model pair; it is ignored and the child inherits the parent route`);
     }
-    const qualified = providers.filter(provider => policy.model.startsWith(`${provider.id}/`)).sort((a, b) => b.id.length - a.id.length)[0];
-    if (qualified !== undefined) {
-        const model = policy.model.slice(qualified.id.length + 1);
-        if (model === '')
-            throw new Error('agent model id must not be empty');
-        return { provider: qualified.id, model };
+    const effort = policy.reasoningEffort;
+    if (effort === undefined && requested === undefined)
+        return undefined;
+    const inherited = parentRouteOf(parent);
+    const provider = requested?.provider ?? inherited.provider;
+    const model = requested?.model ?? inherited.model;
+    if (provider === undefined || model === undefined) {
+        /* v8 ignore next 3 -- an effective route is always known once a parent Agent ran a request. */
+        if (effort !== undefined)
+            diagnose(`agent "${subject}": reasoning effort "${effort}" has no effective route to validate against; it is ignored`);
+        return undefined;
     }
-    const matches = (await Promise.all(providers.map(async (provider) => {
-        try {
-            return (await catalog.listModels(provider.id)).some(model => model.id === policy.model) ? provider.id : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }))).filter((provider) => provider !== undefined);
-    if (matches.length !== 1)
-        throw new Error(`agent model "${policy.model}" ${matches.length === 0 ? 'is not advertised' : 'is ambiguous'}; configure provider and model explicitly`);
-    return { provider: matches[0], model: policy.model };
-}
-/** Read the same declaration for catalog summaries and execution, including inline resources. */
-export async function readAgentRole(entry) {
-    return parseAgentRole(entry.rawText ?? (await readFile(entry.path, 'utf8')));
+    const routeChanged = provider !== inherited.provider || model !== inherited.model;
+    const effectiveEffort = effort ?? (routeChanged ? undefined : inherited.reasoningEffort);
+    try {
+        await llm.resolveCallConfig({ provider, model, ...(effectiveEffort === undefined ? {} : { reasoningEffort: effectiveEffort }) }, signal);
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        diagnose(`agent "${subject}": route ${provider}/${model} is unusable (${String(error)}); it is ignored and the child inherits the parent route`);
+        return undefined;
+    }
+    // Cancellation raised during the adapter lookup must not create a child.
+    signal.throwIfAborted();
+    return {
+        ...(requested ?? {}),
+        ...(effort === undefined ? {} : { reasoningEffort: effort })
+    };
 }
 /** Stable summaries; invalid declarations are excluded and transient read failures abort publication. */
-export async function agentRoleCatalog(entries, signal, diagnose = () => { }) {
+export async function agentRoleCatalog(entries, signal, diagnose = () => { }, projectDir) {
     const summaries = [];
     const counts = new Map();
     for (const entry of entries)
         counts.set(entry.name, (counts.get(entry.name) ?? 0) + 1);
-    for (const entry of entries) {
+    for (const entry of namedAgentRoles(entries)) {
         signal.throwIfAborted();
         if (entry.disabled)
             continue;
@@ -119,7 +138,7 @@ export async function agentRoleCatalog(entries, signal, diagnose = () => { }) {
         }
         let policy;
         try {
-            policy = parseAgentRole(text);
+            policy = expandPolicyPaths(parseAgentRole(text), entry, projectDir);
         }
         catch (error) {
             diagnose(`${entry.path}: ${String(error)}`);
@@ -128,92 +147,109 @@ export async function agentRoleCatalog(entries, signal, diagnose = () => { }) {
         if (policy.disabled)
             continue;
         const description = (policy.description ?? entry.description).replaceAll(/\s+/g, ' ').trim();
+        // Advertise a route only when the executor would apply it.
+        const exact = policy.provider !== undefined && policy.model !== undefined;
         summaries.push({
-            name: entry.name,
-            title: policy.title ?? entry.title ?? entry.name,
+            name: entry.callName,
+            roleId: entry.name,
+            title: policy.title ?? entry.title ?? entry.callName,
             description: description.length <= 500 ? description : `${description.slice(0, 497)}...`,
-            ...(policy.provider === undefined ? {} : { provider: policy.provider }),
-            ...(policy.model === undefined ? {} : { model: policy.model }),
+            ...(exact ? { provider: policy.provider, model: policy.model } : {}),
             ...(policy.reasoningEffort === undefined ? {} : { reasoningEffort: policy.reasoningEffort })
         });
     }
     signal.throwIfAborted();
     return summaries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
-/** Resolve fresh panel state and raw Markdown on every call, including after edits, disabling and uninstall. */
-export async function executeAgentRole(host, listRoles, name, prompt, parent, signal) {
+/** A suite card carries the same path variables as every other surface its author wrote for. */
+function expandPolicyPaths(policy, entry, projectDir) {
+    if (entry.suiteRoot === undefined && entry.suiteData === undefined && projectDir === undefined)
+        return policy;
+    const context = {
+        ...(entry.suiteRoot === undefined ? {} : { root: entry.suiteRoot }),
+        ...(entry.suiteData === undefined ? {} : { data: entry.suiteData }),
+        ...(projectDir === undefined ? {} : { projectDir })
+    };
+    return {
+        ...policy,
+        content: expandPluginPaths(policy.content, context),
+        ...(policy.title === undefined ? {} : { title: expandPluginPaths(policy.title, context) }),
+        ...(policy.description === undefined ? {} : { description: expandPluginPaths(policy.description, context) })
+    };
+}
+/** Read the same declaration for catalog summaries and execution, including inline resources. */
+export async function readAgentRole(entry, projectDir) {
+    return expandPolicyPaths(parseAgentRole(entry.rawText ?? (await readFile(entry.path, 'utf8'))), entry, projectDir);
+}
+/** The calling session's directory, which is what a card's `${CLAUDE_PROJECT_DIR}` names. */
+function sessionCwd(agent) {
+    const cwd = agent?.session?.header?.cwd;
+    return typeof cwd === 'string' && cwd !== '' ? cwd : undefined;
+}
+/**
+ * Start one role child and return its durable id without waiting for the result.
+ * Resume state, steering, and the settlement notice belong to the host's
+ * continuation manager; this executor owns only role resolution.
+ */
+export async function executeAgentRole(host, listRoles, agentName, prompt, parent, signal, diagnose = () => { }) {
     if (parent === undefined)
-        throw new Error('subagents_run requires a calling agent');
+        throw new Error('subagent_run requires a calling agent');
     if (prompt.trim() === '')
-        throw new Error('subagents_run requires a non-empty prompt');
+        throw new Error('subagent_run requires a non-empty prompt');
     signal.throwIfAborted();
-    const entries = (await listRoles(parent)).filter(entry => entry.name === name);
-    if (entries.length !== 1)
-        throw new Error(`agent role "${name}" is unavailable or ambiguous`);
-    const entry = entries[0];
+    const [entry, ...duplicates] = namedAgentRoles(await listRoles(parent)).filter(candidate => candidate.callName === agentName);
+    if (entry === undefined || duplicates.length > 0)
+        throw new Error(`agent "${agentName}" is unavailable or ambiguous`);
     if (entry.disabled)
-        throw new Error(`agent role "${name}" is disabled`);
-    const policy = await readAgentRole(entry);
+        throw new Error(`agent "${agentName}" is disabled`);
+    const policy = await readAgentRole(entry, sessionCwd(parent));
     if (policy.disabled)
-        throw new Error(`agent role "${name}" is disabled`);
-    const agentOptions = { ...(await resolveAgentModel(policy, host.llm)), ...(policy.reasoningEffort === undefined ? {} : { reasoningEffort: policy.reasoningEffort }) };
-    const parentAgent = parent;
-    const parentOptions = parentAgent.session?.requestHeader?.()?.config ?? parentAgent.options ?? {};
-    const provider = agentOptions.provider ?? parentOptions.provider;
-    const model = agentOptions.model ?? parentOptions.model;
-    if (provider === undefined || model === undefined)
-        throw new Error('subagents_run requires an effective provider and model');
-    const routeChanged = provider !== parentOptions.provider || model !== parentOptions.model;
-    const reasoningEffort = agentOptions.reasoningEffort ?? (routeChanged ? undefined : parentOptions.reasoningEffort);
-    await host.llm.resolveCallConfig({ provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }) }, signal);
+        throw new Error(`agent "${agentName}" is disabled`);
+    const agentOptions = await resolveAgentOptions(policy, parent, host.llm, signal, agentName, diagnose);
     signal.throwIfAborted();
-    const run = await host.subagents.start('spawn', {
-        label: name,
-        prompt: [{ type: 'text', text: prompt }],
-        parent,
-        signal,
-        maxDepth: 3,
-        agentOptions,
-        persona: policy.content,
-        ...(policy.tools === undefined && policy.disallowedTools === undefined
-            ? {}
-            : {
-                toolFilter: {
-                    ...(policy.tools === undefined ? {} : { allow: policy.tools }),
-                    ...(policy.disallowedTools === undefined ? {} : { deny: policy.disallowedTools })
-                }
-            })
+    const started = await host.subagents.startContinuable({
+        provider: 'spawn',
+        label: agentName,
+        request: {
+            prompt: [{ type: 'text', text: prompt }],
+            parent,
+            maxDepth: MAX_AGENT_ROLE_DEPTH,
+            persona: policy.content,
+            ...(agentOptions === undefined ? {} : { agentOptions })
+        },
+        signal
     });
-    try {
-        const result = await run.result;
-        if (result.stopReason !== 'completed')
-            throw new Error(`agent role "${name}" stopped: ${result.stopReason}; partial output: ${JSON.stringify(result.output)}`);
-        return { runId: run.id, output: result.output };
-    }
-    finally {
-        await run.dispose();
-    }
+    return { subagentId: started.childId };
 }
 /** Mount once after tools, llm and subagents are available; the returned disposer belongs to the plugin lifecycle. */
 export function mountAgentRoleTool(ctx, listRoles, t = bindHostLocale(undefined)) {
     const host = ctx;
     const tool = defineTool({
         name: AGENT_ROLE_TOOL_NAME,
-        description: 'Delegate a self-contained task to a role from the current subagent catalog and wait for its result. The child starts without the parent conversation. Its saved provider, model, reasoning effort, persona and tool restrictions are applied automatically.',
+        description: 'Delegate a self-contained task to a role from the current subagent catalog. The child starts without the parent conversation and runs ' +
+            'in the background: this returns a durable subagent id immediately. When the run settles the runtime sends you a notice carrying its ' +
+            "outcome and closing message, and send_message steers the child while it runs. The role's saved persona and model settings are applied automatically.",
         parameters: {
-            role: { type: 'string', required: true, description: 'Exact role ID from the current subagent catalog.' },
+            agent: { type: 'string', required: true, description: 'Exact callable role name from the current subagent catalog.' },
             prompt: { type: 'string', required: true, description: 'Complete task and context for the isolated child.' }
         },
-        output: { schema: { type: 'json' }, render: (_args, result) => [{ type: 'text', text: JSON.stringify(result) }] },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: { subagentId: { type: 'string', required: true } }
+            },
+            render: (_args, value) => [{ type: 'text', text: `started subagent ${value.subagentId}` }]
+        },
         isConcurrencySafe: () => true,
         async execute(args, exec) {
-            return executeAgentRole(host, listRoles, args.role, args.prompt, exec.agent, exec.signal);
+            return executeAgentRole(host, listRoles, args.agent, args.prompt, exec.agent, exec.signal, message => ctx.logger?.warn(message));
         }
     });
     const disposeTool = host.tools.register(tool);
     let disposeCatalog;
     try {
-        disposeCatalog = mountSubagentCatalog(ctx, tool, async (agent, signal) => agentRoleCatalog(await listRoles(agent), signal, message => ctx.logger?.warn(message)), t);
+        disposeCatalog = mountSubagentCatalog(ctx, tool, async (agent, signal) => agentRoleCatalog(await listRoles(agent), signal, message => ctx.logger?.warn(message), sessionCwd(agent)), t);
     }
     catch (error) {
         disposeTool();