dsh-agent-plugins-market 0.7.0 → 0.7.2

package/lib/index.js

@@ -4,7 +4,7 @@ import { RuntimeReconciler } from './runtime/reconciler.js';
 import { ReconcileScheduler } from './runtime/reconcile-scheduler.js';
 import { MarketSettingsNamespace } from './runtime/settings-namespace.js';
 import { deleteMcpAuthGrant } from './runtime/mcp-auth-record.js';
-import { inspectToolRegistry } from './runtime/tool-registry-observer.js';
+import { inspectToolRegistry, toolsServiceOf } from './runtime/tool-registry-observer.js';
 import { migratePluginStorage } from './runtime/storage-migration.js';
 import { mountAgentRoleTool } from './runtime/agent-role-router.js';
 import { projectAgentRoles } from './application/project-agent-roles.js';
@@ -13,13 +13,15 @@ import { createPanelResources } from './application/panel-resources.js';
 import { resolveAgentsRoot, resolveDataRoot, resolveUserRoot } from './catalog/paths.js';
 import { mountSuiteRoutes } from './routes.js';
 import { SuiteSkillProvider } from './runtime/skills-provider.js';
+import { shellSeamOf } from './runtime/dynamic-context.js';
 import { loadLspServers } from './runtime/lsp-direct-config.js';
 import { loadDisabledLspServers } from './runtime/lsp-server-state.js';
-import { bindHostLocale, loadHostLocale } from './runtime/host-locale.js';
+import { bindHostLocale, loadHostLocale, readHostLocalePreference, setHostLocaleSource } from './runtime/host-locale.js';
 import { createUserPanelStores } from './runtime/user-panels.js';
 import { SourceAutoUpdater } from './runtime/source-auto-update.js';
 import { UserPanelSkillProvider } from './runtime/user-panels.js';
 import { UserCommandMountRegistry } from './runtime/user-commands.js';
+import { presetSourceRef } from './model/preset-source.js';
 export const name = 'dsh-agent-plugins-market';
 export const inject = ['skills', 'commands'];
 export async function apply(ctx, config = {}) {
@@ -34,10 +36,20 @@ export async function apply(ctx, config = {}) {
     // Host runtime copy resolves from the harness `locale.preference` setting;
     // the async settings read lands before the first session starts in practice.
     const hostLocale = { t: bindHostLocale(undefined) };
-    void loadHostLocale().then(locale => {
-        hostLocale.t = locale.t;
-        providerControl?.invalidate();
-        userPanelControl?.invalidate();
+    const refreshHostLocale = () => {
+        void loadHostLocale().then(locale => {
+            hostLocale.t = locale.t;
+            providerControl?.invalidate();
+            userPanelControl?.invalidate();
+        });
+    };
+    void refreshHostLocale();
+    // The locale preference the GUI writes is owned by the host settings service:
+    // read it there rather than re-parsing the document, and re-bind once the
+    // service lands (the locale namespace may register after this plugin).
+    ctx.inject(['settings'], settingsCtx => {
+        setHostLocaleSource(() => readHostLocalePreference(settingsCtx));
+        refreshHostLocale();
     });
     const runtime = new RuntimeReconciler(ctx, dataRoot, key => hostLocale.t(key));
     // User panel stores (skills / commands / agent personas) and their runtime
@@ -110,9 +122,10 @@ export async function apply(ctx, config = {}) {
     // port below is read at call time: this plugin's apply may run before the
     // credentials, tools and settings services provision, and a snapshot taken
     // here would be permanently undefined even after the service is live.
-    let toolsRegistry;
+    // Read at call time: the tools service provisions after apply() returns.
+    let toolsRegistry = toolsServiceOf(ctx);
     const ports = {
-        mcpToolSnapshot: () => (toolsRegistry === undefined ? [] : inspectToolRegistry(toolsRegistry)),
+        mcpToolSnapshot: () => inspectToolRegistry(toolsRegistry),
         credentialsStore: {
             deleteGrantRecord: async (serverName) => {
                 const store = ctx.get?.('credentials');
@@ -132,7 +145,10 @@ export async function apply(ctx, config = {}) {
     };
     const catalog = new Catalog({ userRoot, dataRoot, agentsRoot, onChanged, ports, ...(config.git === undefined ? {} : { git: config.git }) });
     await catalog.load();
-    await catalog.mergeSources(config.sources ?? []);
+    // Configured seeds first, then the record this plugin presets: the market
+    // lists the first-party collection on the first open, and the ordinary
+    // refresh path clones it. Registration performs no network access.
+    await catalog.mergeSources([...(config.sources ?? []), presetSourceRef()]);
     const resources = createPanelResources(catalog, panels);
     runtime.setMcpOverridesProvider(async () => catalog.allMcpOverrides(await catalog.enabledUserSuites()));
     runtime.lsp.setDirectProvider(async () => (await loadLspServers(agentsRoot)).servers);
@@ -155,9 +171,12 @@ export async function apply(ctx, config = {}) {
         await scheduler.request();
     })
         .catch(() => { });
+    // The shell seam resolves lazily: the service may land after this plugin, and
+    // a profile without one keeps dynamic-context placeholders literal.
+    const shellSeam = () => shellSeamOf(ctx);
     ctx.skills.registerProvider(control => {
         providerControl = control;
-        return new SuiteSkillProvider(catalog);
+        return new SuiteSkillProvider(catalog, { dataRoot, shell: shellSeam });
     });
     // User panel skills ride a second provider so a panel
     // edit invalidates only its own catalog contribution.
@@ -169,14 +188,14 @@ export async function apply(ctx, config = {}) {
         hostCtx.effect(() => mountAgentRoleTool(hostCtx, async (parent) => [
             ...(await resources.agents.list(true)).map(entry => ({ ...entry, title: entry.name, name: entry.id ?? entry.name })),
             ...(await projectAgentRoles(catalog, parent))
-        ], (key, params) => hostLocale.t(key, params)), 'dsh-agent-plugins-market: agent role routing');
+        ]), 'dsh-agent-plugins-market: agent role routing');
     });
     ctx.inject(['agents'], hostCtx => {
         hostCtx.effect(() => {
-            const mounted = mountProjectCommands(hostCtx, catalog, key => hostLocale.t(key));
+            const mounted = mountProjectCommands(hostCtx, catalog, key => hostLocale.t(key), dataRoot);
             const mcp = mountProjectMcp(hostCtx, catalog, dataRoot);
             const hooks = mountProjectHooks(hostCtx, catalog);
-            const prompts = mountSuiteInstructions(hostCtx, catalog);
+            const prompts = mountSuiteInstructions(hostCtx, catalog, dataRoot);
             projectCommands = mounted;
             projectMcp = mcp;
             projectHooks = hooks;

package/lib/model/layouts.js

@@ -12,9 +12,29 @@ export const PLUGIN_LAYOUTS = [
 ];
 /** Kimi Code's primary spelling precedes its compatibility spelling within that dialect. */
 export const MANIFEST_ALIASES = { kimi: ['kimi.plugin.json'] };
+/**
+ * This client's Agent Plugins extension namespace (§8): manifest data rides
+ * `plugin.json` `extensions` under this key, and file-based extensions live
+ * in the top-level directory named exactly this. The namespace contract
+ * version is declared inside the manifest data.
+ */
+export const EXTENSION_NAMESPACE = 'com.deepseek.harness';
+/** Namespace contract versions this manager implements. */
+export const NAMESPACE_SCHEMA_VERSIONS = new Set(['1.0.0']);
+/** Namespace directory locations, relative to the plugin root. */
+export const NAMESPACE_DIR = EXTENSION_NAMESPACE;
+export const NAMESPACE_HOOKS_FILE = joinNamespace(NAMESPACE_DIR, 'hooks', 'hooks.json');
+export const NAMESPACE_LSP_FILE = joinNamespace(NAMESPACE_DIR, 'lsp.json');
+function joinNamespace(...parts) {
+    return parts.join('/');
+}
 /** Equivalent plugin-owned path variables; these never resolve as credentials. */
 export const PLUGIN_ROOT_VARIABLES = new Set(['PLUGIN_ROOT', 'CLAUDE_PLUGIN_ROOT', 'CODEX_PLUGIN_ROOT', 'ZCODE_PLUGIN_ROOT', 'QODER_PLUGIN_ROOT']);
 export const PLUGIN_DATA_VARIABLES = new Set(['PLUGIN_DATA', 'CLAUDE_PLUGIN_DATA', 'ZCODE_PLUGIN_DATA', 'QODER_PLUGIN_DATA']);
+/** Equivalent session project-directory variables; only a calling session supplies the directory. */
+export const PROJECT_DIR_VARIABLES = new Set(['CLAUDE_PROJECT_DIR', 'ZCODE_PROJECT_DIR', 'QODER_PROJECT_DIR']);
+/** Claude Code names the directory holding the skill's own file; no dialect alias exists. */
+export const SKILL_DIR_VARIABLE = 'CLAUDE_SKILL_DIR';
 export const PROJECT_LAYOUTS = [
     {
         dirName: '.claude',
@@ -23,7 +43,12 @@ export const PROJECT_LAYOUTS = [
         mcpFiles: ['.mcp.json'],
         hookFiles: ['.claude/settings.json', '.claude/settings.local.json']
     },
-    { dirName: '.agents', label: 'agents', subdirs: ['skills', 'agents', 'commands'] },
+    {
+        dirName: '.agents',
+        label: 'agents',
+        subdirs: ['skills', 'agents', 'commands'],
+        hookFiles: ['.agents/hooks/hooks.json', '.agents/hooks.json']
+    },
     { dirName: '.codex', label: 'Codex', subdirs: ['skills'], mcpFiles: ['.codex/config.toml'], mcpFormat: 'codex' },
     { dirName: '.cursor', label: 'Cursor', subdirs: ['skills', 'agents', 'commands'], mcpFiles: ['.cursor/mcp.json'] },
     { dirName: '.kimi', label: 'Kimi', subdirs: ['skills'] },
@@ -47,3 +72,21 @@ export const PROJECT_LAYOUTS = [
 ];
 /** Marketplace catalogs follow manifest layout order; the shared root catalog is the fallback. */
 export const MARKETPLACE_PATHS = [...PLUGIN_LAYOUTS.flatMap(layout => layout.marketplaces), 'marketplace.json'];
+/**
+ * Inline top-level manifest keys this manager reads for the portable v1
+ * dialect. The specification's closed manifest schema carries none of them
+ * (§5.2, §6.1), so under `agent-plugin-v1` they are reported as unknown
+ * top-level fields and ignored; every other dialect keeps reading them.
+ */
+export const V1_IGNORED_MANIFEST_KEYS = [
+    'skills',
+    'commands',
+    'agents',
+    'hooks',
+    'mcpServers',
+    'lspServers',
+    'skillInstructions',
+    'systemPrompt',
+    'systemPromptPath',
+    'sessionStart'
+];

package/lib/model/preset-source.js

@@ -0,0 +1,8 @@
+/** Source id the preset record registers under. */
+export const PRESET_SOURCE_ID = 'dsh-agent-plugins';
+/** Repository the preset record points at. */
+export const PRESET_SOURCE_URL = 'https://github.com/Sivan757/dsh-agent-plugins.git';
+/** The preset registration, as the market stores it. */
+export function presetSourceRef() {
+    return { id: PRESET_SOURCE_ID, url: PRESET_SOURCE_URL, kind: 'git' };
+}

package/lib/routes.js

@@ -39,7 +39,14 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
                         sendJson(response, 200, { ok: true, ...value });
                     }
                     catch (error) {
-                        sendJson(response, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+                        // A rejection that names its fields travels with them, so the editor
+                        // can place each reason beside the input it belongs to.
+                        const fields = error.fields;
+                        sendJson(response, 400, {
+                            ok: false,
+                            error: error instanceof Error ? error.message : String(error),
+                            ...(Array.isArray(fields) ? { fields } : {})
+                        });
                     }
                 })();
             }
@@ -77,7 +84,7 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             throw new Error('invalid service kind');
         if (typeof body.id !== 'string' || body.id === '')
             throw new Error('missing service id');
-        await manager.saveServerConfig(body.kind, body.id, body.config);
+        await manager.saveServerConfig(body.kind, body.id, body.config, body.policy);
         return {};
     });
     post(MARKET_ROUTES.addMcpServer, async (body) => {
@@ -86,6 +93,13 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         await manager.addMcpServer(body.name, body.config);
         return {};
     });
+    // Paste import: many services in one write. Each entry reports its own
+    // outcome, so one rejected definition never fails the whole paste.
+    post(MARKET_ROUTES.importMcpServers, async (body) => {
+        const overwrite = body['overwrite'] === true;
+        const result = await manager.importMcpServers(body['servers'], overwrite);
+        return { imported: result.imported, skipped: result.skipped };
+    });
     get(MARKET_ROUTES.lspStatus, async (_request, response) => {
         sendJson(response, 200, await manager.lspStatus());
     });
@@ -257,6 +271,33 @@ 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 {};
+    });
+    // Allow or deny one tool of a declared MCP server. Addressed by the same
+    // source-qualified suite id the status rows carry; the denial lands in the
+    // override record, so the suite's own mcp.json stays source-owned.
+    post(MARKET_ROUTES.setMcpServerTool, async (body) => {
+        const suiteKey = textField(body['suiteId'] ?? '', 'MCP suite id');
+        const serverKey = textField(body['serverKey'] ?? '', 'MCP server key');
+        const tool = textField(body['tool'] ?? '', 'MCP tool name');
+        const enabled = body['enabled'];
+        if (tool === '')
+            throw new Error('missing MCP tool name');
+        if (typeof enabled !== 'boolean')
+            throw new Error('missing boolean enabled');
+        await manager.setMcpServerToolEnabled(suiteKey, serverKey, tool, enabled);
+        return {};
+    });
     // Manual MCP reconcile: retries failed mounts and clears residual tools
     // without touching any catalog state.
     post(MARKET_ROUTES.mcpRetry, async () => {

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

@@ -3,9 +3,9 @@ import { readFile } from 'node:fs/promises';
 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';
 import { namedAgentRoles } from './agent-role-names.js';
-export const AGENT_ROLE_TOOL_NAME = 'subagent_run';
+import { expandPluginPaths } from '../catalog/plugin-variables.js';
+export const AGENT_ROLE_TOOL_NAME = 'subagent_role';
 /**
  * Absolute delegation-depth cap applied to every role child. The host default is
  * the same value; keeping it explicit preserves the shipped recursion budget.
@@ -62,13 +62,17 @@ function parentRouteOf(parent) {
     return agent?.session?.requestHeader?.()?.config ?? agent?.options ?? {};
 }
 /**
- * Resolve the child LLM options one card may contribute.
+ * Resolve the child LLM options for one role call.
  *
- * 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.
+ * The call's own `provider` + `model` pair wins, and the role card supplies the
+ * default when the call names neither. Only an exact pair is applied, and only
+ * when the live LLM runtime accepts it; a bare id, a Claude alias, a lone
+ * `provider` or an unsupported effort degrades to inheriting the parent route
+ * and reports a diagnostic. An explicit route with no explicit effort uses the
+ * selected model's default, so a card's effort never leaks onto a route it was
+ * not written for.
+ * @param policy - the card's parsed routing metadata, used as the default route.
+ * @param requested - the route the call itself asked for.
  * @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.
@@ -76,27 +80,34 @@ function parentRouteOf(parent) {
  * @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)) {
+export async function resolveAgentOptions(policy, requested, parent, llm, signal, subject, diagnose) {
+    const cardRoute = policy.provider !== undefined && policy.model !== undefined ? { provider: policy.provider, model: policy.model } : undefined;
+    if (cardRoute === 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 effort = policy.reasoningEffort;
-    if (effort === undefined && requested === undefined)
+    const callRoute = requested.provider !== undefined && requested.model !== undefined ? { provider: requested.provider, model: requested.model } : undefined;
+    if (callRoute === undefined && (requested.provider !== undefined || requested.model !== undefined)) {
+        const declared = [requested.provider, requested.model].filter(value => value !== undefined).join('/');
+        diagnose(`agent "${subject}": the call's route "${declared}" needs an exact provider and model pair; it is ignored`);
+    }
+    // One value, so a half-specified route can never be forwarded downstream.
+    const route = callRoute ?? cardRoute;
+    const routeEffort = callRoute === undefined ? policy.reasoningEffort : undefined;
+    const effort = requested.reasoningEffort ?? routeEffort;
+    if (effort === undefined && route === undefined)
         return undefined;
     const inherited = parentRouteOf(parent);
-    const provider = requested?.provider ?? inherited.provider;
-    const model = requested?.model ?? inherited.model;
+    const provider = route?.provider ?? inherited.provider;
+    const model = route?.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 routeChanged = provider !== inherited.provider || model !== inherited.model;
-    const effectiveEffort = effort ?? (routeChanged ? undefined : inherited.reasoningEffort);
+    // An explicit route choice starts from the selected model's default effort.
+    const effectiveEffort = effort ?? (route === undefined ? inherited.reasoningEffort : undefined);
     try {
         await llm.resolveCallConfig({ provider, model, ...(effectiveEffort === undefined ? {} : { reasoningEffort: effectiveEffort }) }, signal);
     }
@@ -108,12 +119,12 @@ export async function resolveAgentOptions(policy, parent, llm, signal, subject,
     // Cancellation raised during the adapter lookup must not create a child.
     signal.throwIfAborted();
     return {
-        ...(requested ?? {}),
+        ...(route ?? {}),
         ...(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)
@@ -137,7 +148,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)}`);
@@ -160,74 +171,210 @@ export async function agentRoleCatalog(entries, signal, diagnose = () => { }) {
     signal.throwIfAborted();
     return summaries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
+/** 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) {
-    return parseAgentRole(entry.rawText ?? (await readFile(entry.path, 'utf8')));
+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.
+ * Run one role child through the requested channel.
+ * @param host - the exact live seams this executor owns: tools, llm and subagents.
+ * @param mode - which channel the call asked for.
+ * @param jobs - the host jobs registry; only the `background` channel needs it.
  */
-export async function executeAgentRole(host, listRoles, agentName, prompt, parent, signal, diagnose = () => { }) {
+export async function executeAgentRole(host, listRoles, agentName, prompt, parent, requestedRoute, mode, signal, diagnose = () => { }, jobs) {
     if (parent === undefined)
-        throw new Error('subagent_run requires a calling agent');
+        throw new Error(`${AGENT_ROLE_TOOL_NAME} requires a calling agent`);
     if (prompt.trim() === '')
-        throw new Error('subagent_run requires a non-empty prompt');
+        throw new Error(`${AGENT_ROLE_TOOL_NAME} requires a non-empty prompt`);
     signal.throwIfAborted();
     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 "${agentName}" is disabled`);
-    const policy = await readAgentRole(entry);
+    const policy = await readAgentRole(entry, sessionCwd(parent));
     if (policy.disabled)
         throw new Error(`agent "${agentName}" is disabled`);
-    const agentOptions = await resolveAgentOptions(policy, parent, host.llm, signal, agentName, diagnose);
+    const agentOptions = await resolveAgentOptions(policy, requestedRoute, parent, host.llm, signal, agentName, diagnose);
     signal.throwIfAborted();
-    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
-    });
-    return { subagentId: started.childId };
+    const request = {
+        prompt: [{ type: 'text', text: prompt }],
+        parent,
+        maxDepth: MAX_AGENT_ROLE_DEPTH,
+        persona: policy.content,
+        ...(agentOptions === undefined ? {} : { agentOptions })
+    };
+    if (mode === 'continuable') {
+        const started = await host.subagents.startContinuable({ provider: 'spawn', label: agentName, request, signal });
+        return { kind: 'continuable', subagentId: started.childId };
+    }
+    if (mode === 'background') {
+        if (jobs === undefined) {
+            throw new Error(`background role jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs, or call ${AGENT_ROLE_TOOL_NAME} with run_in_background false`);
+        }
+        // The run's own controller outlives `jobs.start`, which returns at
+        // registration: cancellation and disposal both go through the job's hooks.
+        return {
+            kind: 'background',
+            jobId: jobs.start({
+                kind: 'subagent',
+                label: agentName,
+                owner: parent,
+                run: () => {
+                    const controller = new AbortController();
+                    return {
+                        cancel: (reason) => controller.abort(reason ?? 'background role job killed'),
+                        done: (async () => {
+                            const run = await host.subagents.start('spawn', { ...request, signal: controller.signal });
+                            try {
+                                const result = await run.result;
+                                return result.stopReason === 'completed' ? { status: 'completed' } : { status: 'failed', detail: result.diagnostic ?? result.stopReason };
+                            }
+                            finally {
+                                await run.dispose();
+                            }
+                        })()
+                    };
+                }
+            })
+        };
+    }
+    const run = await host.subagents.start('spawn', { ...request, signal });
+    try {
+        const result = await run.result;
+        if (result.stopReason !== 'completed') {
+            const detail = result.diagnostic === undefined ? '' : `: ${result.diagnostic}`;
+            throw new Error(`agent "${agentName}" did not complete (${result.stopReason})${detail}`);
+        }
+        // The registry performs the authoritative lossless snapshot of the child's
+        // output blocks on the way out, exactly as the host's own delegation tool does.
+        return { kind: 'foreground', runId: run.id, output: result.output };
+    }
+    finally {
+        await run.dispose();
+    }
 }
-/** 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)) {
+/**
+ * Mount once after tools, llm and subagents are available; the returned disposer belongs to the plugin lifecycle.
+ *
+ * The delegation contract lives here rather than in the injected catalog: a tool
+ * description is present in every request, while the catalog message is
+ * re-published whenever roles change, so guidance kept out of the catalog is
+ * sent once and stays readable through compaction.
+ */
+export function mountAgentRoleTool(ctx, listRoles) {
     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. 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.",
+        description: "Delegate a task to a role child defined by an installed plugin: the named role's own instructions and its configured model apply, and the child starts without this conversation. This tool runs in " +
+            'the background by default, immediately returns a durable subagent id, and keeps the child available for later turns; when that run settles, the runtime sends the parent a notice carrying its outcome ' +
+            'and final reply. Set `run_in_background: false` only when your next action depends on receiving the result. A child usually runs for minutes, so while it works on the background path, continue with ' +
+            'independent work instead of waiting. `prompt` must stand alone, since the child cannot see this conversation and a question it asks while it runs goes unanswered. When the notice arrives, verify its ' +
+            "assertions against the files and relay the result to the user; the child's output is not visible to them. The current catalog lists the available roles and states the usage guidance; when no listed " +
+            "role matches, use the host's own `subagent` tools instead.",
         parameters: {
             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.' }
+            prompt: {
+                type: 'string',
+                required: true,
+                description: "The complete, self-contained task for the role child. It does not share this conversation's context, so include everything it needs: what the task is and why, the relevant files and known findings, the output you expect, and the boundaries of the task."
+            },
+            provider: {
+                type: 'string',
+                description: "LLM provider route for the child. Supply together with model to override the route the role card declares; omit both to use the card's route or inherit the parent route."
+            },
+            model: {
+                type: 'string',
+                description: "Model id interpreted by provider. Supply together with provider to override the route the role card declares; omit both to use the card's route or inherit the parent route."
+            },
+            reasoning_effort: {
+                type: 'string',
+                description: "Adapter-owned reasoning effort for the effective child route. Omit to use the card's effort on the card's route, or the selected model's default after an explicit route change."
+            },
+            run_in_background: {
+                type: 'boolean',
+                description: "Which channel runs the child. Omit for the default: a continuable child whose durable subagent id comes back at once, with steering and a settlement notice. Set true for a tracked background job that returns a job id collected with `job_output` and stopped with `job_kill`. Set false for one foreground child whose report comes back as this call's result."
+            }
         },
         output: {
             schema: {
-                type: 'object',
-                additionalProperties: false,
-                properties: { subagentId: { type: 'string', required: true } }
+                oneOf: [
+                    {
+                        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: 'background' },
+                            jobId: { 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: `started subagent ${value.subagentId}` }]
+            render: (_args, value) => [
+                {
+                    type: 'text',
+                    text: value.kind === 'continuable'
+                        ? `started subagent ${value.subagentId}`
+                        : value.kind === 'background'
+                            ? `started background subagent job ${value.jobId}`
+                            : `subagent ${value.runId} finished`
+                }
+            ]
         },
         isConcurrencySafe: () => true,
         async execute(args, exec) {
-            return executeAgentRole(host, listRoles, args.agent, args.prompt, exec.agent, exec.signal, message => ctx.logger?.warn(message));
+            // The parameter keeps the host tool's name and boolean shape while this
+            // tool owns three channels: omitting it keeps the durable child, `true`
+            // runs a tracked job, and `false` returns the report from one foreground run.
+            const mode = args.run_in_background === undefined ? 'continuable' : args.run_in_background ? 'background' : 'foreground';
+            return executeAgentRole(host, listRoles, args.agent, args.prompt, exec.agent, {
+                ...(args.provider === undefined ? {} : { provider: args.provider }),
+                ...(args.model === undefined ? {} : { model: args.model }),
+                ...(args.reasoning_effort === undefined ? {} : { reasoningEffort: args.reasoning_effort })
+            }, mode, exec.signal, message => ctx.logger?.warn(message), ctx.get('jobs'));
         }
     });
     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)));
     }
     catch (error) {
         disposeTool();