@steerable/agent-shell 0.6.28 → 0.6.29

package/contracts/tool-contract.json

@@ -295,6 +295,14 @@
     }
   },
   "version": 2,
+  "dualImplementations": {
+    "todo_write": ["python", "rust"],
+    "web_fetch": ["python", "rust"],
+    "web_search": ["python", "rust"],
+    "run_code": ["python", "rust"],
+    "run_js": ["python", "rust"],
+    "wait_js": ["python", "rust"]
+  },
   "versionAlgorithm": "sha256-utf8-hex",
   "versionToken": {
     "inputField": "expectedVersion",

package/dist/local-backend/agent-capability.d.ts

@@ -14,9 +14,8 @@
  *   2. sidecar 技能目录 —— `SkillTurnContext.exclude`
  *   3. 工具面           —— 每轮 `turnTools`、`tool_search` 结果、反向通道分发复检
  *
- * `@提及` 多个智能体的回合按「最宽松」合并：提及额外专家是为了叠加能力，
- * 不应该反而让对话失去工具或技能（与 personaPreamble 的「同时具备以下 N 个
- * 角色的能力」一致）。
+ * 多个智能体配置按「最宽松」合并（父代理自身、或显式传入的列表）。
+ * `@` 提及不再合并进父的能力面——被点名的智能体走子代理画像。
  */
 export type AgentToolPolicyMode = 'all' | 'allowlist' | 'denylist';
 export interface AgentToolPolicy {
@@ -30,7 +29,7 @@ export interface AgentCapabilityInput {
     loadAllSkills: boolean;
     toolPolicy: AgentToolPolicy;
 }
-/** 本轮生效的能力面（可能是多个被提及智能体的合并结果）。 */
+/** 本轮生效的能力面（可能是多个智能体配置的合并结果）。 */
 export interface AgentCapability {
     /** 正文无条件注入的技能别名（dirName / name / displayName 皆可）。 */
     pinnedSkills: string[];
@@ -74,7 +73,7 @@ export declare function filterToolsByPolicy<T extends {
 /**
  * 合并本轮涉及的全部智能体的能力面，取最宽松。
  *
- * @param agents 按提及顺序排列的智能体配置；空数组表示无绑定。
+ * @param agents 按顺序排列的智能体配置；空数组表示无绑定。
  * @returns 本轮生效的能力面；空数组时为 {@link UNRESTRICTED_CAPABILITY}。
  */
 export declare function mergeAgentCapabilities(agents: readonly AgentCapabilityInput[]): AgentCapability;

package/dist/local-backend/agent-capability.js

@@ -14,9 +14,8 @@
  *   2. sidecar 技能目录 —— `SkillTurnContext.exclude`
  *   3. 工具面           —— 每轮 `turnTools`、`tool_search` 结果、反向通道分发复检
  *
- * `@提及` 多个智能体的回合按「最宽松」合并：提及额外专家是为了叠加能力，
- * 不应该反而让对话失去工具或技能（与 personaPreamble 的「同时具备以下 N 个
- * 角色的能力」一致）。
+ * 多个智能体配置按「最宽松」合并（父代理自身、或显式传入的列表）。
+ * `@` 提及不再合并进父的能力面——被点名的智能体走子代理画像。
  */
 /** 无智能体绑定（或未配置）的回合：不钉技能、不限制。 */
 export const UNRESTRICTED_CAPABILITY = {
@@ -102,7 +101,7 @@ function mergeToolPolicies(a, b) {
 /**
  * 合并本轮涉及的全部智能体的能力面，取最宽松。
  *
- * @param agents 按提及顺序排列的智能体配置；空数组表示无绑定。
+ * @param agents 按顺序排列的智能体配置；空数组表示无绑定。
  * @returns 本轮生效的能力面；空数组时为 {@link UNRESTRICTED_CAPABILITY}。
  */
 export function mergeAgentCapabilities(agents) {

package/dist/local-backend/mention-targets.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@提及` → 被点名的智能体 id。
+ *
+ * 渲染层从 `@` 菜单点选时会把 id 放进 `metadata.mentionedAgentIds`；手打
+ * 的 `@名字` 不带 id。只认 id 的话，手打提及在后端等于没提及：不下发子代理
+ * 画像、不注入强制派发指令，而 Web 顶栏又按正文扫 `@词` 画徽章——界面显示
+ * 点了三个人，实际一个都没派活。这里把正文解析补在后端，两侧同一口径。
+ *
+ * 中文没有词边界，所以按「最长画像名/slug 前缀」匹配，而不是按空白切词：
+ * `@日程规划，帮我…` 里的标点不会被吃进名字。
+ */
+/** 匹配用的智能体子集。 */
+export interface MentionAgentRef {
+    id: string;
+    slug: string | null;
+    name: string;
+}
+/**
+ * 请求体里显式带来的提及 id（`@` 菜单点选的结果）。
+ *
+ * @param payload 发送请求体。
+ * @returns 去重后的 id 列表，保持 `mentionedAgentId` 优先的原有顺序。
+ */
+export declare function collectExplicitMentionIds(payload: Record<string, unknown>): string[];
+/**
+ * 从消息正文里解析 `@名字` / `@slug`。
+ *
+ * @param text 用户消息正文。
+ * @param agents 本会话可用的智能体。
+ * @returns 命中的智能体 id，按正文出现顺序去重。
+ */
+export declare function mentionedAgentIdsFromText(text: string, agents: readonly MentionAgentRef[]): string[];
+/**
+ * 本轮生效的提及 id：显式 id 优先，正文解析补齐。
+ *
+ * @param payload 发送请求体。
+ * @param text 用户消息正文。
+ * @param agents 本会话可用的智能体。
+ * @returns 去重后的 id 列表。
+ */
+export declare function resolveMentionedAgentIds(payload: Record<string, unknown>, text: string, agents: readonly MentionAgentRef[]): string[];

package/dist/local-backend/mention-targets.js

@@ -0,0 +1,88 @@
+/**
+ * `@提及` → 被点名的智能体 id。
+ *
+ * 渲染层从 `@` 菜单点选时会把 id 放进 `metadata.mentionedAgentIds`；手打
+ * 的 `@名字` 不带 id。只认 id 的话，手打提及在后端等于没提及：不下发子代理
+ * 画像、不注入强制派发指令，而 Web 顶栏又按正文扫 `@词` 画徽章——界面显示
+ * 点了三个人，实际一个都没派活。这里把正文解析补在后端，两侧同一口径。
+ *
+ * 中文没有词边界，所以按「最长画像名/slug 前缀」匹配，而不是按空白切词：
+ * `@日程规划，帮我…` 里的标点不会被吃进名字。
+ */
+/**
+ * 请求体里显式带来的提及 id（`@` 菜单点选的结果）。
+ *
+ * @param payload 发送请求体。
+ * @returns 去重后的 id 列表，保持 `mentionedAgentId` 优先的原有顺序。
+ */
+export function collectExplicitMentionIds(payload) {
+    const listed = Array.isArray(payload.mentionedAgentIds)
+        ? payload.mentionedAgentIds.filter((item) => typeof item === 'string' && item.length > 0)
+        : [];
+    const single = typeof payload.mentionedAgentId === 'string' && payload.mentionedAgentId
+        ? [payload.mentionedAgentId]
+        : [];
+    return dedupe([...single, ...listed]);
+}
+/**
+ * 从消息正文里解析 `@名字` / `@slug`。
+ *
+ * @param text 用户消息正文。
+ * @param agents 本会话可用的智能体。
+ * @returns 命中的智能体 id，按正文出现顺序去重。
+ */
+export function mentionedAgentIdsFromText(text, agents) {
+    if (!text.includes('@'))
+        return [];
+    const labels = mentionLabels(agents);
+    if (labels.length === 0)
+        return [];
+    const ids = [];
+    for (let i = 0; i < text.length; i += 1) {
+        if (text[i] !== '@')
+            continue;
+        // 只在行首/空白后开门：邮箱地址与 `a@b` 这类文本不是提及。
+        const prev = i === 0 ? '' : text[i - 1];
+        if (prev && !/\s/.test(prev))
+            continue;
+        const rest = text.slice(i + 1);
+        const matched = labels.find((entry) => rest.slice(0, entry.label.length).toLowerCase() === entry.label.toLowerCase());
+        if (!matched)
+            continue;
+        ids.push(matched.id);
+        i += matched.label.length;
+    }
+    return dedupe(ids);
+}
+/**
+ * 本轮生效的提及 id：显式 id 优先，正文解析补齐。
+ *
+ * @param payload 发送请求体。
+ * @param text 用户消息正文。
+ * @param agents 本会话可用的智能体。
+ * @returns 去重后的 id 列表。
+ */
+export function resolveMentionedAgentIds(payload, text, agents) {
+    const explicit = collectExplicitMentionIds(payload);
+    const known = new Set(agents.map((agent) => agent.id));
+    return dedupe([
+        ...explicit,
+        ...mentionedAgentIdsFromText(text, agents).filter((id) => known.has(id)),
+    ]);
+}
+/** 画像名与 slug 合成匹配表，长名在前——`@调研员组` 不该命中 `调研员`。 */
+function mentionLabels(agents) {
+    const labels = [];
+    for (const agent of agents) {
+        const name = agent.name.trim();
+        const slug = agent.slug?.trim() ?? '';
+        if (name)
+            labels.push({ label: name, id: agent.id });
+        if (slug && slug !== name)
+            labels.push({ label: slug, id: agent.id });
+    }
+    return labels.sort((a, b) => b.label.length - a.label.length);
+}
+function dedupe(ids) {
+    return ids.filter((id, index, all) => all.indexOf(id) === index);
+}

package/dist/local-backend/router.d.ts

@@ -110,17 +110,17 @@ export declare class LocalBackendRouter {
     /**
      * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。
      *
-     * 优先级：payload.mentionedAgentId（@提及）> mentionedAgentIds >
-     * payload.agentId > chat.agentId > 无。@提及多个时按提及顺序合并——
-     * rolePrompt 逐段拼装（第一个为主角色），能力面取最宽松
-     * （见 {@link mergeAgentCapabilities}）。
+     * 父代理 = payload.agentId（专家下拉）> chat.agentId。`@` 提及只进
+     * delegates，不再顶替人设。点到父自己也照样进 delegates：`@` 的语义是
+     * 「起一个子代理」，点自己就是起一个自己的独立副本，父代理仍是拆分与
+     * 汇总的那一个。
      *
      * 必须在拼装工具列表之前调用：`toolPolicy` 决定每轮 `turnTools`，
      * 而工具列表又反过来决定技能的触发条件。
      *
      * @param chatId 当前对话 id。
      * @param payload 前端提交的流请求体。
-     * @returns 本轮的智能体顺序、人设智能体、自称，以及合并后的能力面。
+     * @returns 父代理、委派对象、人设前言与父的能力面。
      */
     private resolveTurnAgents;
     private buildConversationMessages;

package/dist/local-backend/router.js

@@ -8,7 +8,9 @@ import { llmService, getSidecarSupervisor, whenSidecarSupervisor } from '../llm/
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { buildWorldState, getActiveCoreLoopStreamId, streamCoreLoopTurn, } from './coreloop-stream.js';
 import { driveWithAutoContinue, resolveAutoContinueMax, } from './auto-continue-helper.js';
-import { builtinSubagentParam } from './subagent-profiles.js';
+import { buildDelegateDispatchInstruction, buildMentionDelegateRoster, mergeTurnSubagentParam, } from './subagent-profiles.js';
+import { resolveMentionedAgentIds } from './mention-targets.js';
+import { readSidecarHistoryEntries, timelineFromHistoryEntries, } from './task-process.js';
 import { appendTimelineDelta, freezeTimelineReasoning, sealLastTimelineBlock, syncTimelineTools, } from './turn-timeline.js';
 import { turnDurationMs } from './turn-duration.js';
 import { DEFAULT_SYSTEM_PROMPT, telemetryEnabled } from '../storage/index.js';
@@ -153,6 +155,24 @@ function buildLocalAgent() {
         updatedAt: now,
     };
 }
+function parseMessageMetadata(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function persistedAgentIdFromMetadata(raw) {
+    const agentId = parseMessageMetadata(raw)?.agentId;
+    return typeof agentId === 'string' && agentId ? agentId : undefined;
+}
 export class LocalBackendRouter {
     toolRouter;
     defaultStore;
@@ -513,6 +533,20 @@ export class LocalBackendRouter {
                 },
             };
         }
+        // 子代理（delegate_subagent）的推理过程：子回合写自己的 durable record
+        // （`<父 record>:child:<lineage id>`，随 child_spawned 上报），这里按
+        // record 直读重建时间线——与后台任务的过程面板同一套渲染。
+        if (method === 'GET' && pathname === '/api/v2/child-process') {
+            const recordId = url.searchParams.get('recordId')?.trim();
+            if (!recordId) {
+                return { status: 400, data: { detail: 'recordId is required' } };
+            }
+            const entries = readSidecarHistoryEntries(recordId);
+            return {
+                status: 200,
+                data: { recordId, timeline: timelineFromHistoryEntries(entries) },
+            };
+        }
         // 4.6c Task×Worktree：合并到主仓 / 丢弃。两个操作都是幂等目标态
         // （worktreeState 非 pending 时 TaskService 抛错 → 409）。
         const taskActionMatch = pathname.match(/^\/api\/v2\/tasks\/([^/]+)\/(merge|discard)$/);
@@ -671,14 +705,18 @@ export class LocalBackendRouter {
             const chatId = messageListMatch[1];
             const limit = parsePositiveIntParam(url.searchParams.get('limit'), 200);
             const records = await this.store.listMessages(chatId, limit);
-            const messages = records.map(item => ({
-                id: item.id,
-                chatId: item.chatId,
-                role: item.role === 'tool' ? 'assistant' : item.role,
-                content: item.content,
-                createdAt: item.createdAt,
-                messageMetadata: item.messageMetadata,
-            }));
+            const messages = records.map(item => {
+                const agentId = persistedAgentIdFromMetadata(item.messageMetadata);
+                return {
+                    id: item.id,
+                    chatId: item.chatId,
+                    role: item.role === 'tool' ? 'assistant' : item.role,
+                    content: item.content,
+                    createdAt: item.createdAt,
+                    messageMetadata: item.messageMetadata,
+                    ...(agentId ? { agentId } : {}),
+                };
+            });
             // W7-1: 崩溃/强杀中断的 turn 没有 completionStatus 落库——签名是
             // settings_kv 里残留的 turn_active 标记（turn 开始前写、回复落库后
             // 才清）。cancelled/failed 都是活进程写下的终态，标记已清，不在此列。
@@ -1949,8 +1987,14 @@ export class LocalBackendRouter {
         // likewise appends nothing: the crashed turn's user message is already
         // persisted (and already in the durable record).
         let currentUserMessageId;
+        // 本轮被点名的智能体：菜单点选带来的 id 优先，手打的 `@名字` 从正文
+        // 解析补齐（两者缺一，提及就在后端消失，只剩前端徽章）。
+        const mentionedAgentIds = resolveMentionedAgentIds(payload, userMessageText, await this.store.listChatAgents());
         if (!regenerateMatch && !isResume) {
-            const userMessage = await this.store.addMessage(chatId, 'user', userMessageText);
+            const userMeta = mentionedAgentIds.length > 0
+                ? JSON.stringify({ mentionedAgentIds })
+                : null;
+            const userMessage = await this.store.addMessage(chatId, 'user', userMessageText, userMeta);
             currentUserMessageId = userMessage.id;
             emit(this.sseData({ type: 'user_message', message: userMessage }));
         }
@@ -1959,7 +2003,7 @@ export class LocalBackendRouter {
         const chatMode = payload.mode === 'plan' ? 'plan' : 'agent';
         // 本轮生效的智能体：人设、技能勾选、工具策略同源。必须先解析——工具
         // 策略决定工具列表，工具列表又决定技能的触发条件。
-        const turnAgents = await this.resolveTurnAgents(chatId, payload);
+        const turnAgents = await this.resolveTurnAgents(chatId, payload, mentionedAgentIds);
         // Wave 2 工具分层：模型可见列表只出 direct 层（内置工具 + tool_search
         // 发现缝）；MCP 动态工具全在 deferred 层，经 tool_search 命中即调。
         // 附带收益：MCP 目录增删不再改动系统提示词里的工具名录，前缀更稳。
@@ -2003,7 +2047,8 @@ export class LocalBackendRouter {
                 available: turnTools.some((t) => t.name === token),
             };
         }
-        const { systemPrompt, messages, skillContext } = await this.buildConversationMessages(chatId, cleanUserMessageText, payload, turnTools, turnAgents, forcedSkillName, chatMode, forcedMcpTool, currentUserMessageId);
+        const mentionRoster = await buildMentionDelegateRoster(turnAgents.delegates, turnTools.map((tool) => tool.name));
+        const { systemPrompt, messages, skillContext } = await this.buildConversationMessages(chatId, cleanUserMessageText, payload, turnTools, turnAgents, forcedSkillName, chatMode, forcedMcpTool, currentUserMessageId, mentionRoster);
         // A4: the sidecar-hosted CoreLoop is the only chat path (the TS loop
         // was deleted 2026-08-26 after default-on + canary verification). Tools
         // round-trip back to this process over the reverse channel. If the
@@ -2026,6 +2071,8 @@ export class LocalBackendRouter {
             shouldGenerateTitle,
             firstUserMessageForTitle,
             resume: isResume,
+            subagent: mergeTurnSubagentParam(Object.fromEntries(mentionRoster.map((row) => [row.profileName, row.profile]))),
+            parentAgentId: turnAgents.parent?.id ?? null,
         });
     }
     /**
@@ -2128,48 +2175,38 @@ export class LocalBackendRouter {
     /**
      * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。
      *
-     * 优先级：payload.mentionedAgentId（@提及）> mentionedAgentIds >
-     * payload.agentId > chat.agentId > 无。@提及多个时按提及顺序合并——
-     * rolePrompt 逐段拼装（第一个为主角色），能力面取最宽松
-     * （见 {@link mergeAgentCapabilities}）。
+     * 父代理 = payload.agentId（专家下拉）> chat.agentId。`@` 提及只进
+     * delegates，不再顶替人设。点到父自己也照样进 delegates：`@` 的语义是
+     * 「起一个子代理」，点自己就是起一个自己的独立副本，父代理仍是拆分与
+     * 汇总的那一个。
      *
      * 必须在拼装工具列表之前调用：`toolPolicy` 决定每轮 `turnTools`，
      * 而工具列表又反过来决定技能的触发条件。
      *
      * @param chatId 当前对话 id。
      * @param payload 前端提交的流请求体。
-     * @returns 本轮的智能体顺序、人设智能体、自称，以及合并后的能力面。
+     * @returns 父代理、委派对象、人设前言与父的能力面。
      */
-    async resolveTurnAgents(chatId, payload) {
-        const mentionedAgentIds = Array.isArray(payload.mentionedAgentIds)
-            ? payload.mentionedAgentIds.filter((s) => typeof s === 'string')
-            : [];
-        const orderedAgentIds = [
-            ...(typeof payload.mentionedAgentId === 'string' && payload.mentionedAgentId
-                ? [payload.mentionedAgentId]
-                : []),
-            ...mentionedAgentIds,
-        ].filter((id, idx, arr) => arr.indexOf(id) === idx);
-        if (orderedAgentIds.length === 0) {
-            const fallbackId = (typeof payload.agentId === 'string' && payload.agentId) ||
-                (await this.store.getChat(chatId))?.agentId ||
-                null;
-            if (fallbackId)
-                orderedAgentIds.push(fallbackId);
-        }
-        const agents = (await Promise.all(orderedAgentIds.map((id) => this.store.getChatAgent(id))))
-            .filter((agent) => Boolean(agent));
+    async resolveTurnAgents(chatId, payload, mentionedAgentIds) {
+        const parentId = (typeof payload.agentId === 'string' && payload.agentId) ||
+            (await this.store.getChat(chatId))?.agentId ||
+            null;
+        const parent = parentId ? await this.store.getChatAgent(parentId) : null;
+        const delegates = [];
+        for (const id of mentionedAgentIds) {
+            const agent = await this.store.getChatAgent(id);
+            if (agent)
+                delegates.push(agent);
+        }
         return {
-            orderedAgentIds,
-            // 能力面来自全部解析到的智能体，人设前言只用配了 rolePrompt 的那些——
-            // 自建智能体可以只勾技能、不写人设。自称始终跟第一个解析到的智能体，
-            // 不要求写了人设——否则没 rolePrompt 的角色会回落成产品品牌。
-            personaAgents: agents.filter((agent) => Boolean(agent.rolePrompt)),
-            identityName: agents[0]?.name.trim() || null,
-            capability: mergeAgentCapabilities(agents),
+            parent,
+            delegates,
+            personaAgents: parent?.rolePrompt ? [parent] : [],
+            identityName: parent?.name.trim() || null,
+            capability: mergeAgentCapabilities(parent ? [parent] : []),
         };
     }
-    async buildConversationMessages(chatId, latestUserMessage, payload, turnTools, turnAgents, forcedSkillName, chatMode = 'agent', forcedMcpTool, currentUserMessageId) {
+    async buildConversationMessages(chatId, latestUserMessage, payload, turnTools, turnAgents, forcedSkillName, chatMode = 'agent', forcedMcpTool, currentUserMessageId, mentionRoster = []) {
         // 跨轮压缩由框架 CoreLoop 拥有：token 压力触发 CompactionHooks（已接真实
         // summarizer），压缩边界持久化到 durable record，W6-10 透视 reconcile 保证
         // 压缩跨轮存活。桌面把全量原始历史作为种子发给框架——不再维护桌面侧滚动
@@ -2370,6 +2407,14 @@ export class LocalBackendRouter {
         if (finalUserImages.notes.length > 0) {
             finalUserContent = `${finalUserContent}\n\n【附件图片】\n${finalUserImages.notes.join('\n')}`;
         }
+        if (mentionRoster.length > 0) {
+            finalUserContent = `${finalUserContent}\n\n${buildDelegateDispatchInstruction(mentionRoster.map((row) => ({
+                name: row.name,
+                profileName: row.profileName,
+                toolFilter: row.profile.toolFilter,
+                isSelf: row.agentId === turnAgents.parent?.id,
+            })))}`;
+        }
         return {
             // W2.8.2: the system prompt travels as a typed fragment param (cap
             // enforced sidecar-side), not as a leading system message.
@@ -2771,7 +2816,7 @@ export class LocalBackendRouter {
      * the reverse-channel handler registered in main.ts.
      */
     async handleCoreLoopTurn(args) {
-        const { chatId, systemPrompt, messages, skillContext, turnTools, toolPolicy, chatMode, payload, emit, signal, shouldGenerateTitle, firstUserMessageForTitle, resume, } = args;
+        const { chatId, systemPrompt, messages, skillContext, turnTools, toolPolicy, chatMode, payload, emit, signal, shouldGenerateTitle, firstUserMessageForTitle, resume, subagent, parentAgentId, } = args;
         const supervisor = getSidecarSupervisor();
         if (!supervisor) {
             emit(this.sse('error', { message: 'coreloop enabled but sidecar is not running' }));
@@ -2936,7 +2981,7 @@ export class LocalBackendRouter {
                 // 带工具域/轮次/并发/系统提示,模型按画像 description 选委派
                 // 对象;per-profile model 留给设置面。子代理作为 AgentPool 池化
                 // 子运行执行,生命周期经 onChildEvent → SSE 进 UI 编排卡片。
-                subagent: builtinSubagentParam(),
+                subagent,
                 // 六件套(agent_spawn/send/wait/close/list/interrupt)收缩为
                 // opt-in 高级模式:STEERABLE_ORCHESTRATION=1 开启;开启后与
                 // delegate 共享同一 AgentPool(同一 maxParallel 预算)。
@@ -3024,8 +3069,23 @@ export class LocalBackendRouter {
                 onChildEvent: (event) => {
                     // P3.1: forward child-agent lifecycle to the renderer; it renders
                     // the orchestration card (spawn → running → terminal status).
-                    children.push({ ...event });
-                    emit(this.sseData({ type: 'orchestration_child', ...event }));
+                    // Narrowed to the lifecycle fields: the sidecar's `agent.child`
+                    // notification also carries its per-stream `streamId`, which has no
+                    // meaning once the stream ends and must not reach the persisted
+                    // assistant metadata below.
+                    const lifecycle = {
+                        kind: event.kind,
+                        childId: event.childId,
+                        ...(event.task !== undefined ? { task: event.task } : {}),
+                        ...(event.depth !== undefined ? { depth: event.depth } : {}),
+                        ...(event.status !== undefined ? { status: event.status } : {}),
+                        ...(event.error !== undefined ? { error: event.error } : {}),
+                        ...(event.profile !== undefined ? { profile: event.profile } : {}),
+                        // 子代理自己的 durable record：右侧过程面板据此回看它的推理与工具。
+                        ...(event.recordId !== undefined ? { recordId: event.recordId } : {}),
+                    };
+                    children.push(lifecycle);
+                    emit(this.sseData({ type: 'orchestration_child', ...lifecycle }));
                 },
             };
             // 自动续跑：`budget_exhausted` 是「被预算墙截停」而不是「模型认为做
@@ -3131,6 +3191,8 @@ export class LocalBackendRouter {
             mode: chatMode,
             coreloop: true,
             traceId: outcomeTraceId,
+            ...(parentAgentId ? { agentId: parentAgentId } : {}),
+            ...(children.length > 0 ? { orchestrationChildEvents: children } : {}),
             ...(durationMs != null ? { durationMs } : {}),
             ...(autoContinuations > 0 ? { autoContinuations } : {}),
             ...(turnFiles.length > 0 ? { turnFiles } : {}),

package/dist/local-backend/subagent-profiles.d.ts

@@ -1,5 +1,6 @@
 /**
- * 内置 subagent_type 画像集（CC `.claude/agents` parity）。
+ * 内置 subagent_type 画像集（CC `.claude/agents` parity）以及
+ * ChatAgent → 提及子代理画像的映射（`@` 委派 W1）。
  *
  * 桌面不再向 sidecar 传裸 `subagent: true`——命名画像让每个委派带
  * 工具域 / 轮次上限 / 并发性 / 系统提示，模型按画像 description 选择
@@ -11,7 +12,9 @@
  * - per-profile model 刻意不设：跟随父模型；模型路由留给设置面。
  * - 画像系统提示是种进子 loop 的第一条 system 消息（子代理看不到
  *   主对话的系统提示，画像提示就是它的全部角色设定）。
+ * - W2 落地前 toolFilter 必须与父本轮工具面取交集（子 ⊆ 父）。
  */
+import { type AgentCapabilityInput, type AgentToolPolicy } from './agent-capability.js';
 export interface BuiltinSubagentProfile {
     toolFilter?: string[];
     maxRounds?: number;
@@ -19,6 +22,22 @@ export interface BuiltinSubagentProfile {
     description: string;
     systemPrompt?: string;
 }
+/** 映射用的智能体子集（身份 + 能力面），不依赖存储层类型。 */
+export interface SubagentAgentInput extends AgentCapabilityInput {
+    id: string;
+    slug: string | null;
+    name: string;
+    rolePrompt: string | null;
+    description?: string | null;
+}
+/** 一次 `@` 提及转出的画像，连同显示名，供派发指令与 sidecar 参数共用。 */
+export interface MentionDelegateProfile {
+    /** 被提及智能体的 id——调用方据此认出自提及那一行。 */
+    agentId: string;
+    name: string;
+    profileName: string;
+    profile: BuiltinSubagentProfile;
+}
 export declare const BUILTIN_SUBAGENT_PROFILES: Record<string, BuiltinSubagentProfile>;
 /**
  * chat.stream 的 `subagent` 参数：内置画像集。调用方（普通回合与
@@ -28,3 +47,71 @@ export declare const BUILTIN_SUBAGENT_PROFILES: Record<string, BuiltinSubagentPr
 export declare function builtinSubagentParam(): {
     profiles: Record<string, BuiltinSubagentProfile>;
 };
+/**
+ * 画像名：优先稳定 ASCII slug，否则英文名 slugify，再否则 `agent-<id>`。
+ *
+ * @param agent 被提及的智能体。
+ * @returns 可作为 `subagent_type` enum 的画像名。
+ */
+export declare function profileNameForAgent(agent: {
+    id: string;
+    slug: string | null;
+    name: string;
+}): string;
+/**
+ * W2 过渡期：子策略放行的工具与父本轮工具面取交集。
+ * 交集等于父全集时不设 filter（子继承父的工具域）。
+ *
+ * @param childPolicy 子智能体自己的工具策略。
+ * @param parentToolNames 父本轮已经广告给模型的工具名。
+ * @returns 子代理 toolFilter；`undefined` 表示不比父更窄。
+ */
+export declare function resolveChildToolFilter(childPolicy: AgentToolPolicy, parentToolNames: readonly string[]): string[] | undefined;
+/**
+ * 把本轮被 `@` 的智能体译成 sidecar 画像（含 W1 夹紧）。
+ *
+ * @param delegates 被 `@` 的智能体，按提及顺序（含被点名的父代理本身）。
+ * @param parentToolNames 父本轮模型可见工具名。
+ * @returns 画像名 → 画像。
+ */
+export declare function buildMentionSubagentProfiles(delegates: readonly SubagentAgentInput[], parentToolNames: readonly string[]): Promise<Record<string, BuiltinSubagentProfile>>;
+/**
+ * 与 {@link buildMentionSubagentProfiles} 同源，额外带显示名供派发指令使用。
+ *
+ * @param delegates 被 `@` 的智能体，按提及顺序（含被点名的父代理本身）。
+ * @param parentToolNames 父本轮模型可见工具名。
+ * @returns 提及顺序的画像花名册。
+ */
+export declare function buildMentionDelegateRoster(delegates: readonly SubagentAgentInput[], parentToolNames: readonly string[]): Promise<MentionDelegateProfile[]>;
+/**
+ * 注入本轮最后一条用户消息的强制派发指令。
+ *
+ * 被点名的父代理自己也在名单里（`isSelf`）：它要起一个独立副本去跑那份
+ * 子任务，而不是顺手自己做——否则 `requiredProfiles` 完成门会一直把回合
+ * 退回来。
+ *
+ * @param delegates 被点名的子代理（显示名 + 画像名 + 实际工具面 + 是否是自己）。
+ * @returns 派发指令正文。
+ */
+export declare function buildDelegateDispatchInstruction(delegates: ReadonlyArray<{
+    name: string;
+    profileName: string;
+    toolFilter?: string[];
+    isSelf?: boolean;
+}>): string;
+export interface TurnSubagentParam {
+    profiles: Record<string, BuiltinSubagentProfile>;
+    maxParallel?: number;
+    /** 本轮必须收到委派的画像（被 `@` 的智能体）；sidecar 据此挂完成门。 */
+    requiredProfiles?: string[];
+}
+/**
+ * 内置画像 + 本轮提及画像。被 `@` 超过 4 个时抬高池的并行上限。
+ *
+ * 提及画像同时作为 `requiredProfiles` 下发：强制派发此前只是提示词里的
+ * 一句话，模型跑了别的工具再叙述「已启动」就能蒙过所有既有纪律检查。
+ *
+ * @param mentionProfiles 本轮提及转出的画像；空对象则与 {@link builtinSubagentParam} 相同。
+ * @returns 下发给 sidecar 的 `subagent` 参数。
+ */
+export declare function mergeTurnSubagentParam(mentionProfiles: Record<string, BuiltinSubagentProfile>): TurnSubagentParam;

package/dist/local-backend/subagent-profiles.js

@@ -1,5 +1,6 @@
 /**
- * 内置 subagent_type 画像集（CC `.claude/agents` parity）。
+ * 内置 subagent_type 画像集（CC `.claude/agents` parity）以及
+ * ChatAgent → 提及子代理画像的映射（`@` 委派 W1）。
  *
  * 桌面不再向 sidecar 传裸 `subagent: true`——命名画像让每个委派带
  * 工具域 / 轮次上限 / 并发性 / 系统提示，模型按画像 description 选择
@@ -11,7 +12,11 @@
  * - per-profile model 刻意不设：跟随父模型；模型路由留给设置面。
  * - 画像系统提示是种进子 loop 的第一条 system 消息（子代理看不到
  *   主对话的系统提示，画像提示就是它的全部角色设定）。
+ * - W2 落地前 toolFilter 必须与父本轮工具面取交集（子 ⊆ 父）。
  */
+import { isToolAllowed, mergeAgentCapabilities, normalizeToolPolicy, resolveSkillExcludes, } from './agent-capability.js';
+import { buildSystemPrompt } from './prompt-builder.js';
+import { loadSkills } from './skill-loader.js';
 /** 只读工具域：探索与调研画像共享的「摸不到写操作」基线。 */
 const READ_ONLY_TOOLS = [
     'local_read_file',
@@ -21,10 +26,10 @@ const READ_ONLY_TOOLS = [
     'web_fetch',
     'mcp_list_tools',
 ];
+const READ_ONLY_TOOL_SET = new Set(READ_ONLY_TOOLS);
 export const BUILTIN_SUBAGENT_PROFILES = {
     explore: {
         toolFilter: READ_ONLY_TOOLS,
-        maxRounds: 12,
         concurrent: true,
         description: '只读代码侦察。搜索、读文件、定位「在哪里/是什么」类问题；不做任何修改，返回带路径:行号的发现。',
         systemPrompt: [
@@ -37,7 +42,6 @@ export const BUILTIN_SUBAGENT_PROFILES = {
     },
     research: {
         toolFilter: [...READ_ONLY_TOOLS, 'local_write_file'],
-        maxRounds: 16,
         concurrent: true,
         description: '深度调研。多轮 web 搜索/抓取并交叉验证，给出带来源 URL 的结论；可把报告写入文件。',
         systemPrompt: [
@@ -52,7 +56,6 @@ export const BUILTIN_SUBAGENT_PROFILES = {
     coder: {
         // 不设 toolFilter：全工具域。写操作串行（concurrent: false），避免两个
         // 实现代理同时改同一批文件。
-        maxRounds: 16,
         concurrent: false,
         description: '全工具实现代理。改代码、跑命令、自验结果；适合自包含的实现/修复任务。',
         systemPrompt: [
@@ -72,3 +75,176 @@ export const BUILTIN_SUBAGENT_PROFILES = {
 export function builtinSubagentParam() {
     return { profiles: BUILTIN_SUBAGENT_PROFILES };
 }
+/**
+ * 画像名：优先稳定 ASCII slug，否则英文名 slugify，再否则 `agent-<id>`。
+ *
+ * @param agent 被提及的智能体。
+ * @returns 可作为 `subagent_type` enum 的画像名。
+ */
+export function profileNameForAgent(agent) {
+    const slug = agent.slug?.trim() ?? '';
+    if (isStableProfileName(slug))
+        return slug;
+    const fromName = slugifyProfileName(agent.name);
+    if (fromName)
+        return fromName;
+    const fromId = agent.id.replace(/[^a-zA-Z0-9]/g, '').slice(0, 16);
+    return fromId ? `agent-${fromId}` : 'agent';
+}
+function isStableProfileName(value) {
+    return /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(value);
+}
+function slugifyProfileName(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40);
+}
+/**
+ * W2 过渡期：子策略放行的工具与父本轮工具面取交集。
+ * 交集等于父全集时不设 filter（子继承父的工具域）。
+ *
+ * @param childPolicy 子智能体自己的工具策略。
+ * @param parentToolNames 父本轮已经广告给模型的工具名。
+ * @returns 子代理 toolFilter；`undefined` 表示不比父更窄。
+ */
+export function resolveChildToolFilter(childPolicy, parentToolNames) {
+    const policy = normalizeToolPolicy(childPolicy);
+    const allowed = parentToolNames.filter((name) => isToolAllowed(policy, name));
+    // `all` 且交集等于父全集 → 不设 filter，子代理继承父的工具域。
+    // allowlist / denylist 始终下发交集清单，即使碰巧等于父全集——画像
+    // roster 要让模型看见该子代理真正收窄后的工具面。
+    if (policy.mode === 'all')
+        return undefined;
+    return allowed;
+}
+function isReadOnlyToolDomain(toolNames) {
+    return toolNames.every((name) => READ_ONLY_TOOL_SET.has(name));
+}
+function profileDescription(agent) {
+    const summary = (agent.rolePrompt || agent.description || '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 80);
+    return summary ? `${agent.name} — ${summary}` : agent.name;
+}
+/**
+ * 把本轮被 `@` 的智能体译成 sidecar 画像（含 W1 夹紧）。
+ *
+ * @param delegates 被 `@` 的智能体，按提及顺序（含被点名的父代理本身）。
+ * @param parentToolNames 父本轮模型可见工具名。
+ * @returns 画像名 → 画像。
+ */
+export async function buildMentionSubagentProfiles(delegates, parentToolNames) {
+    const roster = await buildMentionDelegateRoster(delegates, parentToolNames);
+    return Object.fromEntries(roster.map((row) => [row.profileName, row.profile]));
+}
+/**
+ * 与 {@link buildMentionSubagentProfiles} 同源，额外带显示名供派发指令使用。
+ *
+ * @param delegates 被 `@` 的智能体，按提及顺序（含被点名的父代理本身）。
+ * @param parentToolNames 父本轮模型可见工具名。
+ * @returns 提及顺序的画像花名册。
+ */
+export async function buildMentionDelegateRoster(delegates, parentToolNames) {
+    const roster = [];
+    const used = new Set();
+    for (const agent of delegates) {
+        let profileName = profileNameForAgent(agent);
+        if (used.has(profileName)) {
+            const suffix = agent.id.replace(/[^a-zA-Z0-9]/g, '').slice(0, 8);
+            profileName = suffix ? `${profileName}-${suffix}` : `${profileName}-dup`;
+        }
+        used.add(profileName);
+        roster.push({
+            agentId: agent.id,
+            name: agent.name,
+            profileName,
+            profile: await buildOneMentionProfile(agent, parentToolNames),
+        });
+    }
+    return roster;
+}
+async function buildOneMentionProfile(agent, parentToolNames) {
+    const toolFilter = resolveChildToolFilter(agent.toolPolicy, parentToolNames);
+    const domain = toolFilter ?? parentToolNames;
+    const readOnly = isReadOnlyToolDomain(domain);
+    const capability = mergeAgentCapabilities([agent]);
+    const excludeSkillNames = capability.allowExternalSkills
+        ? ['plan-mode']
+        : resolveSkillExcludes(capability, await loadSkills({ ignoreConditions: true }), ['plan-mode']);
+    const personaPreamble = agent.rolePrompt
+        ? `【当前角色】${agent.name}\n${agent.rolePrompt}`
+        : '';
+    const built = await buildSystemPrompt({
+        personaPreamble,
+        identityName: agent.name,
+        pinnedSkillNames: capability.pinnedSkills,
+        ignoreConditions: capability.loadAllSkills,
+        excludeSkillNames,
+        toolNames: domain,
+    });
+    return {
+        ...(toolFilter ? { toolFilter } : {}),
+        concurrent: readOnly,
+        description: profileDescription(agent),
+        systemPrompt: built.prompt,
+    };
+}
+/**
+ * 注入本轮最后一条用户消息的强制派发指令。
+ *
+ * 被点名的父代理自己也在名单里（`isSelf`）：它要起一个独立副本去跑那份
+ * 子任务，而不是顺手自己做——否则 `requiredProfiles` 完成门会一直把回合
+ * 退回来。
+ *
+ * @param delegates 被点名的子代理（显示名 + 画像名 + 实际工具面 + 是否是自己）。
+ * @returns 派发指令正文。
+ */
+export function buildDelegateDispatchInstruction(delegates) {
+    const names = delegates.map((row) => row.name).join('、');
+    const roster = delegates
+        .map((row) => {
+        const tools = row.toolFilter?.length
+            ? `本轮可用工具：${row.toolFilter.join('、')}`
+            : '本轮可用工具与你相同';
+        const self = row.isSelf ? '就是你自己的画像，起一个独立副本去跑；' : '';
+        return `- **${row.name}**（subagent_type=\`${row.profileName}\`）：${self}${tools}`;
+    })
+        .join('\n');
+    const hasSelf = delegates.some((row) => row.isSelf);
+    return [
+        `用户点名了 **${names}**。本轮你必须把活交给它们，用 \`delegate_subagent\`（\`subagent_type\` 填画像名），每人至少一份子任务。`,
+        '',
+        roster,
+        '',
+        '- 子任务**彼此独立**时：一句话说明分工，紧接着在**同一轮**把全部调用发出，并把可并行的排在一起。',
+        '- 子任务**有依赖**时：按依赖顺序分轮派发，并把前一轮的结论写进后一轮的 `task`。',
+        '- 每份 `task` 必须自包含（目标、输入、交付形式、验收标准）——子代理看不到本对话。',
+        '- 禁止只写分工然后停手；也禁止漏掉任何一位被点名的代理。',
+        ...(hasSelf
+            ? [
+                '- 名单里包含你自己时同样要发 `delegate_subagent`：那是一个看不到本对话的独立副本，自己顺手做不算完成派发。',
+            ]
+            : []),
+        '- 若某子代理注明了本轮可用工具，不要尝试让它调用未列出的工具。',
+    ].join('\n');
+}
+/**
+ * 内置画像 + 本轮提及画像。被 `@` 超过 4 个时抬高池的并行上限。
+ *
+ * 提及画像同时作为 `requiredProfiles` 下发：强制派发此前只是提示词里的
+ * 一句话，模型跑了别的工具再叙述「已启动」就能蒙过所有既有纪律检查。
+ *
+ * @param mentionProfiles 本轮提及转出的画像；空对象则与 {@link builtinSubagentParam} 相同。
+ * @returns 下发给 sidecar 的 `subagent` 参数。
+ */
+export function mergeTurnSubagentParam(mentionProfiles) {
+    const mentionNames = Object.keys(mentionProfiles);
+    return {
+        profiles: { ...BUILTIN_SUBAGENT_PROFILES, ...mentionProfiles },
+        ...(mentionNames.length > 4 ? { maxParallel: mentionNames.length } : {}),
+        ...(mentionNames.length > 0 ? { requiredProfiles: mentionNames } : {}),
+    };
+}

package/dist/sidecar/types.d.ts

@@ -354,16 +354,26 @@ export interface SidecarChatStreamRequest {
     subagent?: boolean | {
         toolFilter?: string[];
         maxParallel?: number;
+        /** Child round / tool-error walls; default to the parent loop's. */
+        maxRounds?: number;
+        maxToolErrors?: number;
         profiles?: Record<string, {
             toolFilter?: string[];
             model?: string;
             maxRounds?: number;
+            maxToolErrors?: number;
             concurrent?: boolean;
             description?: string;
             /** Profile system prompt, seeded as the child loop's first message
              * (CC `.claude/agents` body parity). */
             systemPrompt?: string;
         }>;
+        /**
+         * Profiles that MUST each receive a delegation this turn (the host's
+         * `@` mentions). A `completed` turn that skipped one is retried — the
+         * dispatch instruction alone is prompt text a model can narrate past.
+         */
+        requiredProfiles?: string[];
     };
     /** A6 layered skill disclosure: the sidecar injects the catalog layer
      * (first-round pre_step, recorded as a hook_action event) and answers
@@ -555,6 +565,12 @@ export interface SidecarChildEvent {
     status?: string;
     error?: string;
     profile?: string;
+    /**
+     * The child's own durable record (`<parent record>:child:<lineage id>`),
+     * present on `child_spawned` when the host wired a history store. Read it
+     * back to render the delegation's reasoning + tool calls.
+     */
+    recordId?: string;
 }
 export interface SidecarChatStreamHandlers {
     onChunk?: (chunk: SidecarStreamChunk) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.28",
+  "version": "0.6.29",
   "description": "Steerable framework — product-neutral desktop/headless agent host (Tier 5). Electron main + preload + headless HTTP server (BS) sharing one storage/sidecar/tooling core; scenario packs extend it through the @steerable/pack-sdk contract and are composed at build time by the consuming product.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -49,9 +49,9 @@
     "electron-store": "^8.1.0",
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
-    "@steerable/agent-harness": "0.6.28",
-    "@steerable/pack-sdk": "0.6.28",
-    "@steerable/agent-protocol": "0.6.28"
+    "@steerable/agent-harness": "0.6.29",
+    "@steerable/pack-sdk": "0.6.29",
+    "@steerable/agent-protocol": "0.6.29"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",